Virtual Scroll
Looking for ion-virtual-scroll
?
ion-virtual-scroll
was deprecated in v6.0.0 and removed in v7.0.0. We recommend using a Vue library to accomplish this. We outline one approach using vue-virtual-scroller
below.
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';
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';
Next, we need to install this in our Vue application:
app.use(VueVirtualScroller);
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';
Next, we need to add the component to our Vue application:
app.component('RecycleScroller', RecycleScroller);
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>
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%;
}
Usage with Ionic Components
Ionic Framework requires that features such as collapsible large titles, ion-infinite-scroll
, ion-refresher
, and ion-reorder-group
be used within an ion-content
. To use these experiences with virtual scrolling, you must add the .ion-content-scroll-host
class to the virtual scroll viewport.
For example:
<template>
<ion-page>
<ion-content :scroll-y="false">
<RecycleScroller class="ion-content-scroll-host scroller">
<!-- Your existing content and configurations -->
</RecycleScroller>
</ion-content>
</ion-page>
</template>
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.