import VirtualScroller from 'primevue/virtualscroller';
<script src="https://unpkg.com/primevue@^3/core/core.min.js"></script>
VirtualScroller is used to display huge data. It periodically adds special elements defined according to the scroll's position to the DOM. The item and itemSize properties and item template are required on
component. In addition, an initial array is required based on the total number of items to display.
VirtualScroller automatically calculates how many items will be displayed in the view according to itemSize using a specified scroll height. Its scroll height can be adjusted with scrollHeight property or height property
of CSS.
<VirtualScroller :items="basicItems" :itemSize="50">
<template v-slot:item="{ item, options }">
<div :class="['scroll-item p-2', {'odd': options.odd}]" style="height: 50px">{{ item }}</div>
</template>
</VirtualScroller>
export default {
data() {
return {
basicItems: null
}
},
mounted() {
this.basicItems = Array.from({ length: 100000 }).map((_, i) => `Item #${i}`);
}
}
VirtualScroller has a special loader. It can be activated with the showLoader property. In addition, loader template can be used to add custom loaders to item elements.
<VirtualScroller :items="basicItems" :itemSize="50" showLoader :delay="250">
<template v-slot:item="{ item, options }">
<div :class="['scroll-item p-2', {'odd': options.odd}]" style="height: 50px">{{ item }}</div>
</template>
<template v-slot:loader="{ options }">
<div :class="['scroll-item p-2', {'odd': options.odd}]" style="height: 50px" >
<Skeleton :width="options.even ? '60%' : '50%'" height="1.3rem" />
</div>
</template>
</VirtualScroller>
Lazy mode is handy to deal with large datasets, instead of loading the entire data, small chunks of data is loaded by invoking lazy-load event.
<VirtualScroller :items="lazyItems" :itemSize="50" showLoader :delay="250" :loading="lazyLoading" :lazy=true @lazy-load="onLazyLoad">
<template v-slot:item="{ item, options }">
<div :class="['scroll-item p-2', {'odd': options.odd}]" style="height: 50px">{{ item }}</div>
</template>
</VirtualScroller>
export default {
data() {
return {
lazyItems: null,
lazyLoading: false,
loadLazyTimeout: null,
}
},
mounted() {
this.lazyItems = Array.from({ length: 100000 });
},
methods: {
onLazyLoad(event) {
this.lazyLoading = true;
if (this.loadLazyTimeout) {
clearTimeout(this.loadLazyTimeout);
}
//imitate delay of a backend call
this.loadLazyTimeout = setTimeout(() => {
const { first, last } = event;
const lazyItems = [...this.lazyItems];
for (let i = first; i < last; i++) {
lazyItems[i] = `Item #${i}`;
}
this.lazyItems = lazyItems;
this.lazyLoading = false;
}, Math.random() * 1000 + 250);
}
}
}
| Name | Type | Default | Description |
|---|---|---|---|
| id | string | null | Unique identifier of the element. |
| style | any | null | Inline style of the component. |
| class | string | null | Style class of the component. |
| items | array | null | An array of objects to display. |
| itemSize | number / [number, number] | null | The height/width of item according to orientation. |
| scrollHeight | string | null | Height of the scroll viewport. |
| scrollWidth | string | null | Width of the scroll viewport. |
| orientation | string | 'vertical' | The orientation of scrollbar, valid values are 'vertical', 'horizontal' and 'both'. |
| numToleratedItems | number | null |
Determines how many additional elements to add to the DOM outside of the view. According to the scrolls made up and down, extra items are added in a certain algorithm in the form of multiples of this number. Default value is half the number of items shown in the view. |
| delay | number | 0 | Delay in scroll before new data is loaded. |
| lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
| disabled | boolean | false | If disabled, the VirtualScroller feature is eliminated and the content is displayed directly. |
| loaderDisabled | boolean | false | Used to implement a custom loader instead of using the loader feature in the VirtualScroller. |
| loading | boolean | false | Whether the data is loaded. |
| showSpacer | boolean | true | Used to implement a custom spacer instead of using the spacer feature in the VirtualScroller. |
| showLoader | boolean | false | Whether to show loader. |
| tabindex | number | 0 | Index of the element in tabbing order. |
| Name | Parameters | Description |
|---|---|---|
| scroll | event: Browser event | Callback to invoke when scroll position changes. |
| scroll-index-change |
event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. |
Callback to invoke when scroll position and item's range in view changes. |
| lazy-load |
event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. |
Callback to invoke in lazy mode to load new data. |
| Name | Parameters | Description |
|---|---|---|
| scrollTo |
left: Left position of scroll. top: Top position of scroll behavior: Behavior of scroll, valid values are 'auto' and 'smooth' |
Scroll to move to a specific position. |
| scrollToIndex |
index: Index of item according to orientation mode. behavior: Behavior of scroll, valid values are 'auto' and 'smooth' |
Scroll to move to a specific item. |
| scrollInView |
index: Index of item according to orientation mode. to: Defines the location of the item in view, valid values are 'to-start' and 'to-end'. behavior: Behavior of scroll, valid values are 'auto' and 'smooth' |
It is used to move the specified index into the view. It is a method that will usually be needed when keyboard support is added to the virtualScroller component. |
| getRenderedRange | - | Returns the range of items added to the DOM. |
| Name | Parameters |
|---|---|
| content |
items: An array of objects to display. styleClass: Style class of the component contentRef: Referance of the content getItemOptions: Options of the items loading: Whether the data is loaded getLoaderOptions: Loader options of the items while the data is loading. itemSize: The height/width of item according to orientation. rows: The number of the rendered rows. columns: The number of the rendered columns. spacerStyle: The style of spacer element. contentStyle: The style of content element. vertical: Whether the orientation is vertical. horizontal: Whether the orientation is horizontal. both: Whether the orientation is both. |
| item |
item: Item instance options: Options of the item instance |
| loader | options: Options of the loader items |
Following is the list of structural style classes, for theming classes visit
| Name | Element |
|---|---|
| p-virtualscroller | Container element. |
| p-virtualscroller-content | Content element. |
| p-virtualscroller-loader | Loader element. |
VirtualScroller has no specific role is enforced, still you may use any aria role and attributes as any valid attribute is passed to the container element.
Component does not include any built-in interactive elements.
None.