VirtualScroller

Import via Module

import { VirtualScroller } from 'primereact/virtualscroller';
 

Import via CDN

<script src="https://unpkg.com/primereact/core/core.min.js"></script>
<script src="https://unpkg.com/primereact/virtualscroller/virtualscroller.min.js"></script>
 

Getting Started

VirtualScroller is used to display huge data. It periodically adds special elements defined according to the scroll's position to the DOM. The itemSize and itemTemplate properties 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={items} itemSize={50} itemTemplate={itemTemplate} />
 

const items = Array.from({ length: 100000 }).map((_, i) => `Item #${i}`);

const itemTemplate = (item, options) => {
    // item: Current item.
    // options.index: Index of the item.
    // options.count: Total numbers of items.
    // options.first: Whether this is the first item.
    // options.last: Whether this is the last item.
    // options.even: Whether the index is even.
    // options.odd: Whether the index is odd.
    // options.props: Props of component.

    return <div style={{ height: '50px' }}>{item}</div>;
}
 

Loader

VirtualScroller has a special loader. It can be activated with the showLoader property. In addition, loadingTemplate can be used to add custom loaders to item elements.

<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} showLoader delay={250} />

<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} showLoader delay={250} loadingTemplate={loadingTemplate} />
 

const loadingTemplate = (options) => {
    // options.index: Index of the item.
    // options.count: Total numbers of items.
    // options.first: Whether this is the first item.
    // options.last: Whether this is the last item.
    // options.even: Whether the index is even.
    // options.odd: Whether the index is odd.
    // options.props: Props of component.
    // options.numCols: Total number of columns in a row in 'both' orientation mode in view.

    return (
        <div style={{ height: '50px' }}>
            <Skeleton width={options.even ? '60%' : '50%'} height="1.3rem" />
        </div>
    );
}
 

Lazy

Lazy mode is handy to deal with large datasets, instead of loading the entire data, small chunks of data is loaded by invoking onLazyLoad callback.

<VirtualScroller items={lazyItems} itemSize={50} itemTemplate={itemTemplate} lazy onLazyLoad={onLazyLoad}
    showLoader loading={lazyLoading} />
 

const onLazyLoad = (event) => {
    setLazyLoading(true);

    if (loadLazyTimeout) {
        clearTimeout(loadLazyTimeout);
    }

    //imitate delay of a backend call
    loadLazyTimeout = setTimeout(() => {
        const { first, last } = event;
        const _lazyItems = [...lazyItems];

        for (let i = first; i < last; i++) {
            _lazyItems[i] = `Item #${i}`;
        }

        setLazyItems(_lazyItems)
        setLazyLoading(true);
    }, Math.random() * 1000 + 250);
}
 

Content Template

VirtualScroller has a HTML div element to wrap the all items. But in some cases, it may be desirable to define a completely special wrapper element instead of the HTML div element. The contentTemplate property can be used for this. This will be especially necessary to maintain the DOM layout and provide accessibility.

<VirtualScroller items={items} itemSize={50} itemTemplate={itemTemplate} contentTemplate={contentTemplate} />
 

const contentTemplate = (options) => {
    // options.className: Class name of wrapper element.
    // options.contentRef: Ref of wrapper element.
    // options.spacerRef: Ref of spacer element.
    // options.stickyRef: Ref of sticky element in content.
    // options.items: Loaded data.
    // options.getItemOptions(index): Information of any item.
    // options.children: Items of wrapper element.
    // options.element: Default wrapper element.
    // options.props: Props of component.
    // options.loading: Whether the data is loaded.
    // options.getLoaderOptions(index): Information of any item during the loading.
    // options.loadingTemplate: Template of loading item.
    // options.itemSize: The height/width of item according to orientation.
    // options.vertical: Whether the orientation is vertical.
    // options.horizontal: Whether the orientation is horizontal.
    // options.both: Whether the orientation is both.

    return (
        <ul ref={options.contentRef} className={options.className} role="listbox">
            {options.children}
        </ul>
    );
}

const itemTemplate = (item, options) => {
    return <li role="option" style={{ height: '50px' }}>{item}</li>
}
 

Properties

Events

Methods

Styling

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

Accessibility

This section is under development. After the necessary tests and improvements are made, it will be shared with the users as soon as possible.

Dependencies

None.