Search docs/

Virtual Scroll

One virtual scrolling solution to consider for your Ionic Vue app is vue-virtual-scroller. This guide will go over how to install vue-virtual-scroller into your Ionic Vue application and use it with other Ionic components.

Installation

To setup the virtual scroller, first install vue-virtual-scroller:

npm install vue-virtual-scroller@next

:::note Be sure to use the next tag otherwise you will get a version of vue-virtual-scroll that is only compatible with Vue 2. ::: From here, we need to import the virtual scroller's CSS into our app. In main.ts, add the following line:

import 'vue-virtual-scroller/dist/vue-virtual-scroller.css';
CopyCopied

Registering Virtual Scroll Components

Now that we have the package installed and the CSS imported, we can either import all virtual scroll components or only import the components we want to use. This guide will show how to do both.

Installing all Components

To install all virtual scroll components for use your app, add the following import to main.ts:

import VueVirtualScroller from 'vue-virtual-scroller';
CopyCopied

Next, we need to install this in our Vue application:

app.use(VueVirtualScroller);
CopyCopied

After doing this, all virtual scroll components will be available for use in our app.

:::note Installing all components may result in unused virtual scroll components being added to your application bundle. See the Installing Specific Components section below for an approach that works better with treeshaking. :::

Installing Specific Components

To install specific virtual scroll components for use in your app, import the component you want to use in main.ts. In this example, we will be using the RecycleScroller component:

import { RecycleScroller } from 'vue-virtual-scroller';
CopyCopied

Next, we need to add the component to our Vue application:

app.component('RecycleScroller', RecycleScroller);
CopyCopied

After doing this, we will be able to use the RecycleScroller component in our app.

Usage

This example will use the RecycleScroller component which only renders the visible items in your list. Other components such as DynamicScroller can be used when you do not know the size of the items in advance.

The RecycleScroller component should be added inside of your ion-content component:

<template>
  <ion-page>
    <ion-content>
      <ion-list>
        <RecycleScroller
          class="scroller"
          :items="list"
          :item-size="56"
        >
          <template #default="{ item }">
            <ion-item>
              <ion-avatar slot="start">
                <img src="https://picsum.photos/seed/picsum/40/40" />
              </ion-avatar>
              <ion-label>{{ item }}</ion-label>
            </ion-item>
          </template>
        </RecycleScroller>
      </ion-list>
    </ion-content>
  </ion-page>
</template>

<script>
  import { defineComponent, ref } from 'vue';
  import {
    IonAvatar,
    IonContent,
    IonItem,
    IonLabel,
    IonPage
  } from '@ionic/vue';

  export default defineComponent({
    components: {
      IonAvatar,
      IonContent,
      IonItem,
      IonLabel,
      IonPage
    },
    setup() {
      const list = ref([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

      return { list }
    }
  });
</script>
CopyCopied

There are two important pieces we need to account for in order for RecycleScroller to work. First, we need to provide it with an array of data to iterate over via the items property. In this case, we have an array called list which provides our data. Second, we need to provide the size of each node via the item-size property. If you do not know the size of the node ahead of time, you should use the DynamicScroller component instead.

Now that our template is setup, we need to add some CSS to size the virtual scrolling viewport correctly. In a style tag in your component, add the following:

.scroller {
  height: 100%;
}
CopyCopied

A Note on Ionic Components

Certain Ionic Framework functionality is currently not compatible with virtual scrolling. Features such as collapsible large titles, ion-infinite-scroll, and ion-refresher rely on being able to scroll on ion-content itself, and as a result will not work when using virtual scrolling.

We are working to improve compatibility between these components and virtual scrolling solutions. You can follow progress and give feedback here: https://github.com/ionic-team/ionic-framework/issues/23437.

Further Reading

This guide only covers a small portion of what vue-virtual-scroller is capable of. For more details, please see the vue-virtual-scroller documentation.

Previous
Navigation/Routing
Next
Slides