File: virtualscroller.md | Updated: 11/15/2025
Introducing PrimeReact v11 Alpha 🥁Learn More
SearchK
10.9.7
FEATURES
API
THEMING
PASS THROUGH
VirtualScroller is a performant approach to render large amounts of data efficiently.
Import#
import { VirtualScroller } from 'primereact/virtualscroller';
Copy
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 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} itemTemplate={itemTemplate}
className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />
Copy
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} itemTemplate={itemTemplate} orientation="horizontal"
className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />
Copy
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]} itemTemplate={itemTemplate} orientation="both"
className="border-1 surface-border border-round" style={{ width: '200px', height: '200px' }} />
Copy
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} 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} />
Copy
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
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} 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' }} />
Copy
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 _lazy_property 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' }} />
Copy
Accessibility#
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.
Component does not include any built-in interactive elements.
Import
Basic
Horizontal
Grid
Delay
Loading
Lazy
Accessibility
PrimeReact 10.9.7 by PrimeTek