V3 has reached EOL, Upgrade to PrimeVue 4

VirtualScroller

VirtualScroller is a performant approach to render large amounts of data efficiently.

Import #


import VirtualScroller from 'primevue/virtualscroller';

Basic #

VirtualScroller requires items as the data to display, itemSize for the dimensions of an item and item template are required on component. In addition, an initial array is required based on the total number of items to display. Size of the viewport is configured using scrollWidth, scrollHeight properties directly or with CSS width and height styles.

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7


<VirtualScroller :items="items" :itemSize="50" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

Horizontal #

Setting orientation to horizontal enables scrolling horizontally. In this case, the itemSize should refer to the width of an item.

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7


<VirtualScroller :items="items" :itemSize="50" orientation="horizontal" class="border-1 surface-border border-round" style="width: 200px; height: 200px" :pt="{ content: 'flex flex-row' }">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="width: 50px; writing-mode: vertical-lr;">{{ item }}</div>
    </template>
</VirtualScroller>

Grid #

Scrolling can be enabled vertically and horizontally when orientation is set as both. In this mode, itemSize should be an array where first value is the height of an item and second is the width.

Item #0_0

Item #0_1

Item #0_2

Item #0_3

Item #1_0

Item #1_1

Item #1_2

Item #1_3

Item #2_0

Item #2_1

Item #2_2

Item #2_3

Item #3_0

Item #3_1

Item #3_2

Item #3_3

Item #4_0

Item #4_1

Item #4_2

Item #4_3

Item #5_0

Item #5_1

Item #5_2

Item #5_3

Item #6_0

Item #6_1

Item #6_2

Item #6_3

Item #7_0

Item #7_1

Item #7_2

Item #7_3


<VirtualScroller :items="items" :itemSize="[50, 100]" orientation="both" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">
            <template v-for="(el, index) of item" :key="index">
                <div style="width: 100px">{{ el }}</div>
            </template>
        </div>
    </template>
</VirtualScroller>

Delay #

The delay property adds a threshold to wait in milliseconds during scrolling for render optimization.

No Delay

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7

150ms

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7

500ms

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7


<VirtualScroller :items="items" :itemSize="50" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

<VirtualScroller :items="items" :itemSize="50" :delay="150" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

<VirtualScroller :items="items" :itemSize="50" :delay="500" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

Loading #

Busy state is enabled by adding showLoader property which blocks the UI with a modal by default. Alternatively, loader template can be used to customize items e.g. with Skeleton.

Modal

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7

Skeleton

Item #0

Item #1

Item #2

Item #3

Item #4

Item #5

Item #6

Item #7


<VirtualScroller :items="items" :itemSize="50" showLoader :delay="250" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

<VirtualScroller :items="items" :itemSize="50" showLoader :delay="250" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
    <template v-slot:loader="{ options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">
            <Skeleton :width="options.even ? '60%' : '50%'" height="1.3rem" />
        </div>
    </template>
</VirtualScroller>

Lazy #

Lazy mode is handy to deal with large datasets, instead of loading the entire data, small chunks of data is loaded on demand. To implement lazy loading, enable the lazyproperty and implement onLazyLoad callback to return data.


<VirtualScroller :items="lazyItems" :itemSize="50" showLoader :delay="250" :loading="lazyLoading" lazy @lazy-load="onLazyLoad" class="border-1 surface-border border-round" style="width: 200px; height: 200px">
    <template v-slot:item="{ item, options }">
        <div :class="['flex align-items-center p-2', { 'surface-hover': options.odd }]" style="height: 50px">{{ item }}</div>
    </template>
</VirtualScroller>

Accessibility #

Screen Reader

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.

Keyboard Support

Component does not include any built-in interactive elements.

name	type	default	description
id	string	null	Unique identifier of the element.
style	any	null	Inline style of the component.
class	any	null	Style class of the component.
items	null \| any[] \| any[][]	null	An array of objects to display.
itemSize	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	"both" \| "horizontal" \| "vertical"	vertical	The orientation of scrollbar.
numToleratedItems	number	half the number of items shown in the view.	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.
delay	number	0	Delay in scroll before new data is loaded.
resizeDelay	number	10	Delay after window's resize finishes.
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.
showLoader	boolean	false	Whether to show loader.
showSpacer	boolean	true	Used to implement a custom spacer instead of using the spacer feature in the VirtualScroller.
loading	boolean	false	Whether to load items.
tabindex	string \| number	0	Index of the element in tabbing order.
inline	boolean	false	When enabled, positions the content as inline.
step	number	0	Used to specify how many items to load in each load method in lazy mode.
appendOnly	boolean	false	Used to append each loaded item to top without removing any items from the DOM. Using very large data may cause the browser to crash.
autoSize	boolean	false	Whether to dynamically change the height or width of scrollable container.
pt	PassThrough<VirtualScrollerPassThroughOptions	null	Used to pass attributes to DOM elements inside the component.
ptOptions	PassThroughOptions	null	Used to configure passthrough(pt) options of the component.
unstyled	boolean	false	When enabled, it removes component related styles in the core.

name	parameters	returnType	description
update:numToleratedItems	value: number	void	Emitted when the numToleratedItems changes.
scroll	event: Event	void	Callback to invoke when scroll position changes.
scroll-index-change	event: VirtualScrollerScrollIndexChangeEvent	void	Callback to invoke when scroll position and item's range in view changes.
lazy-load	event: VirtualScrollerLazyEvent	void	Callback to invoke in lazy mode to load new data.

name	parameters	returnType	description
content	scope: { items: any, // An array of objects to display for virtualscroller styleClass: string, // Style class of the content contentRef: (el: any) ⇒ void, // Referance of the content getItemOptions: (index: number) ⇒ VirtualScrollerItemOptions, // Options of the items loading: boolean, // Whether the data is loaded. getLoaderOptions: (index: number, ext: any) ⇒ VirtualScrollerLoaderOptions, // Loader options of the items while the data is loading. itemSize: undefined, // The height/width of item according to orientation. rows: undefined, // The number of the rendered rows. columns: undefined, // The number of the rendered columns. spacerStyle: any, // The style of spacer element. contentStyle: any, // The style of content element. vertical: boolean, // Whether the orientation is vertical. horizontal: boolean, // Whether the orientation is horizontal. both: boolean, // Whether the orientation is both. }	VNode<RendererNode, RendererElement, Object>[]	Custom content template.
item	scope: { item: any, // Item data. options: VirtualScrollerItemOptions, // Item options. }	VNode<RendererNode, RendererElement, Object>[]	Custom item template.
loader	scope: { options: VirtualScrollerLoaderOptions, // Loader options. }	VNode<RendererNode, RendererElement, Object>[]	Custom loader template.
loadingicon	scope: { class: string, // Style class of the icon. }	VNode<RendererNode, RendererElement, Object>[]	Custom loading icon template.

name	parameters	returnType	description
scrollTo	options: ScrollToOptions	void	Scroll to move to a specific position.
scrollToIndex	index: number	void	Scroll to move to a specific item.
scrollInView	index: number	void	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		VirtualScrollerRangeMethod	Returns the range of items added to the DOM.

name	type	description
first	number	First index of the new data range to be loaded.
last	number	Last index of the new data range to be loaded.

VirtualScroller

Import #

Basic #

Horizontal #

Grid #

Delay #

Loading #

Lazy #

Accessibility #

Screen Reader

Keyboard Support

VirtualScroller API

VirtualScroller #

Props #

Emits #

Slots #

Methods #

Events #

VirtualScrollerScrollIndexChangeEvent #

VirtualScrollerLazyEvent #

Interfaces #

VirtualScrollerPassThroughMethodOptions #

VirtualScrollerViewport #

VirtualScrollerRangeMethod #

VirtualScrollerItemOptions #

VirtualScrollerPassThroughOptions #

VirtualScrollerPassThroughAttributes #

VirtualScrollerState #

VirtualScrollerLoaderOptions #

Types #

VirtualScrollerPassThroughOptionType #

name	type	default	description
instance	any	null	Defines instance.
props	VirtualScrollerProps	null	Defines valid properties.
state	VirtualScrollerState	null	Defines current inline state.
attrs	any	null	Defines valid attributes.
parent	any	null	Defines parent options.
global	undefined \| object	null	Defines passthrough(pt) options in global config.

name	type	default	description
index	number	null	Item index
count	number	null	Items count
first	boolean	null	Whether the item is first.
last	boolean	null	Whether the item is last.
even	boolean	null	Whether the item is even.
odd	boolean	null	Whether the item is odd.
[key: string]	any	null

name	type	default	description
root	VirtualScrollerPassThroughOptionType	null	Used to pass attributes to the root's DOM element.
content	VirtualScrollerPassThroughOptionType	null	Used to pass attributes to the content's DOM element.
loader	VirtualScrollerPassThroughOptionType	null	Used to pass attributes to the loader's DOM element.
loadingIcon	VirtualScrollerPassThroughOptionType	null	Used to pass attributes to the loading icon's DOM element.
spacer	VirtualScrollerPassThroughOptionType	null	Used to pass attributes to the spacer's DOM element.
hooks	ComponentHooks	null	Used to manage all lifecycle hooks.