lara-light-indigo

VirtualScroller

VirtualScroller is a performant approach to handle huge data efficiently.

Basic
Vertical
Horizontal
Both
Scroll Delay
0ms Delay
150ms Delay
250ms Delay
Loading
Basic
Template
Lazy
Template
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
NameTypeDefaultDescription
idstringnullUnique identifier of the element.
styleobjectnullInline style of the component.
classNameanynullStyle class of the component.
itemsarraynullAn array of objects to display.
itemSizenumber / [number, number]nullThe height/width of item according to orientation.
scrollHeightstringnullHeight of the scroll viewport.
scrollWidthstringnullWidth of the scroll viewport.
orientationstring'vertical'The orientation of scrollbar, valid values are 'vertical', 'horizontal' and 'both'.
numToleratedItemsnumbernullDetermines 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.
delaynumber0Delay in scroll before new data is loaded.
lazybooleanfalseDefines if data is loaded and interacted with in lazy manner.
disabledbooleanfalseIf disabled, the VirtualScroller feature is eliminated and the content is displayed directly.
loaderDisabledbooleanfalseUsed to implement a custom loader instead of using the loader feature in the VirtualScroller.
loadingbooleanfalseWhether the data is loaded.
showSpacerbooleantrueUsed to implement a custom spacer instead of using the spacer feature in the VirtualScroller.
showLoaderbooleanfalseWhether to show loader.
loadingTemplateanynullThe template of loader.
itemTemplateanynullThe template of item.
contentTemplateanynullThe template of item's wrapper element.
Events
NameParametersDescription
onScrollevent: Browser eventCallback to invoke when scroll position changes.
onScrollIndexChangeevent.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.
onLazyLoadevent.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.
Methods
NameParametersDescription
scrollToleft: 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.
scrollToIndexindex: Index of item according to orientation mode.
behavior: Behavior of scroll, valid values are 'auto' and 'smooth'
Scroll to move to a specific item.
scrollInViewindex: 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.
Styling

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

NameElement
p-virtualscrollerContainer element.
p-virtualscroller-contentContent element.
p-virtualscroller-loaderLoader element.
Dependencies

None.

Component Scale

Input Style

Ripple Effect

Free Themes

Built-in component themes created by the PrimeReact Theme Designer.

Bootstrap
Blue
Purple
Blue
Purple
Material Design
Indigo
Deep Purple
Indigo
Deep Purple
Material Design Compact
Indigo
Deep Purple
Indigo
Deep Purple
Tailwind
Tailwind Light
Fluent UI
Blue
PrimeOne Design - 2022 NEW
Lara Indigo
Lara Blue
Lara Purple
Lara Teal
Lara Indigo
Lara Blue
Lara Purple
Lara Teal
PrimeOne Design - 2021
Saga Blue
Saga Green
Saga Orange
Saga Purple
Vela Blue
Vela Green
Vela Orange
Vela Purple
Arya Blue
Arya Green
Arya Orange
Arya Purple
Premium Themes

Premium themes are only available exclusively for PrimeReact Theme Designer subscribers and therefore not included in PrimeReact core.

Soho Light
Soho Dark
Viva Light
Viva Dark
Mira
Nano

Legacy Free Themes

Nova
Nova Alt
Nova Accent
Luna Blue
Luna Green
Luna Amber
Luna Pink
Rhea

Premium Create-React-App Templates

Beautifully crafted premium create-react-app application templates by the PrimeTek design team.

Sakai
Atlantis
Freya
Ultima
Diamond
Sapphire
Serenity
Babylon
Avalon
Apollo
Roma