VirtualScroller

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

Import#


import { VirtualScroller } from 'primereact/virtualscroller';

Basic#

VirtualScroller requires items as the data to display, itemSize for the dimensions of an item and itemTemplate to define the content per item. Size of the viewport is configured usingscrollWidth, scrollHeight properties directly or with CSS width and height styles.


<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} 
    className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />

Horizontal#

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


<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} orientation="horizontal"
    className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />

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.


<VirtualScroller items={items} itemSize={[50, 100]} itemTemplate={itemTemplate} orientation="both" 
    className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />

Delay#

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

No Delay

150ms

500ms


<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />
<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} delay={150} />
<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} delay={500} />

Loading#

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

Modal

Skeleton


<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} showLoader delay={250} className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />
<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} showLoader delay={250} loadingTemplate={loadingTemplate} className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />

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} itemTemplate={itemTemplate} lazy onLazyLoad={onLazyLoad} 
    loadingTemplate={loadingTemplate} showLoader loading={lazyLoading} 
    className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />

Style#

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-virtualscroller	Container element.
p-virtualscroller-content	Content element.
p-virtualscroller-loader	Loader element.
p-virtualscroller-both	Container element when horizontal and vertical scrolling enabled.
p-virtualscroller-horizontal	Container element when horizontal orientation.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility#

Screen Reader

VirtualScroller uses a semantic list element to list the items. No specific role is enforced, still you may use any aria role and attributes as any valid attribute is passed to the container element. List element can be also customized for accessibility using listProps property.

Keyboard Support

Component does not include any built-in interactive elements.