VirtualScroller

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

Import #


import { VirtualScrollerModule } from 'primeng/virtualscroller';

Basic #

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



<p-virtualScroller [value]="items" class="border-1 surface-border border-round" [style]="{'width': '200px'}" scrollHeight="200px" [itemSize]="50">
    <ng-template pTemplate="item" let-item>
        <div class="flex align-items-center p-2 h-full" [ngClass]="{ 'surface-hover': item.index % 2 === 0 }">
            {{ item.label }}
        </div>
    </ng-template>
</p-virtualScroller>

Template #

Header and Footer are the two sections that are capable of displaying custom content by using header and footer templates.

Header Content



<p-virtualScroller [value]="items" class="border-1 surface-border border-round" [style]="{ width: '200px' }" scrollHeight="200px" [itemSize]="50">
    <ng-template pTemplate="header">Header Content</ng-template>
    <ng-template pTemplate="item" let-item>
        <div class="flex align-items-center p-2 h-full" [ngClass]="{ 'surface-hover': item.index % 2 === 0 }">
            {{ item.label }}
        </div>
    </ng-template>
    <ng-template pTemplate="footer">Footer Content</ng-template>
</p-virtualScroller>

Lazy Load #

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.

List of Products



<p-virtualScroller [value]="virtualProducts" scrollHeight="450px" [itemSize]="100" [lazy]="true" (onLazyLoad)="loadCarsLazy($event)">
    <ng-template pTemplate="header"> List of Products </ng-template>
    <ng-template let-product pTemplate="item">
        <div class="flex align-items-center p-3 w-full flex-wrap">
            <div>
                <img src="https://primefaces.org/cdn/primeng/images/demo/product/{{ product.image }}" [alt]="product.name" class="mr-3 w-4rem md:w-7rem shadow-2" />
            </div>
            <div class="flex-1">
                <h5 class="mb-2 text-base">{{ product.name }}</h5>
                <i class="pi pi-tag hidden md:inline vertical-align-middle mr-2"></i>
                <span class="hidden md:inline-flex vertical-align-middle mr-2">{{ product.category }}</span>
            </div>
            <div class="flex flex-column align-items-end">
                <h6 style="width:25px; height:14px;" class="mb-2">{{ '$' + product.price }}</h6>
                <p-tag [value]="product.inventoryStatus" [severity]="getSeverity(product.inventoryStatus)"></p-tag>
            </div>
        </div>
    </ng-template>
    <ng-template let-product pTemplate="loadingItem">
        <div class="flex align-items-center p-3 w-full flex-wrap loading-item">
            <div class="mr-3" style="width:100px; height:66px;"></div>
            <div class="flex-1">
                <h5 class="mb-2 text-base"></h5>
                <i class="hidden md:inline vertical-align-middle mr-2"></i>
                <span class="hidden md:inline-flex vertical-align-middle mr-2"></span>
            </div>
            <div class="flex flex-column align-items-end">
                <h6 style="width:25px; height:14px;" class="mb-2"></h6>
                <span class="block h-2rem" style="width:100px"></span>
            </div>
        </div>
    </ng-template>
</p-virtualScroller>

Programmatic Scroll #

Scrolling to a specific index can be done with the scrollToIndex function.



<p-button label="Reset" (click)="reset()"></p-button>
<p-virtualScroller #vs [value]="items" class="border-1 surface-border border-round" [style]="{ width: '200px' }" scrollHeight="200px" [itemSize]="50">
    <ng-template pTemplate="item" let-item>
        <div class="flex align-items-center p-2 h-full" [ngClass]="{ 'surface-hover': item.index % 2 === 0 }">
            {{ item.label }}
        </div>
    </ng-template>
</p-virtualScroller>

Style #

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

Name	Element
p-virtualscroller	Container element.
p-virtualscroller-header	Header section.
p-virtualscroller-footer	Footer section.
p-virtualscroller-content	Content section.
p-virtualscroller-list	List element.

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.

VirtualScroller API

API defines helper props, events and others for the PrimeNG VirtualScroller module.

VirtualScroller #

VirtualScroller is a performant approach to handle huge data efficiently.

Properties #

Defines the input properties of the component.

name	type	default	description
value	any[]	null	An array of objects to display.
itemSize	number	null	Height of an item in the list.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
scrollHeight	any	null	Max height of the content area in inline mode.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
options	ScrollerOptions	null	Whether to use the scroller feature. The properties of scroller component can be used like an object in it.
delay	number	250	Threshold in milliseconds to delay lazy loading during scrolling.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onLazyLoad	event : VirtualScrollerLazyLoadEvent	Callback to invoke in lazy mode to load new data.

Templates #

Defines the templates used by the component.

name	parameters	description
item	context : { $implicit: any, // Item instance. options: ScrollerOptions, // Scroller options. }	Custom item template.
header	null	Custom header template.
footer	null	Custom header template.

Interfaces #

Defines the custom interfaces used by the module.

ScrollerOptions #

Options for the scroller.

name	type	description
id	string	Unique identifier of the element.
style	Object	Inline style of the component.
styleClass	string	Style class of the element.
tabindex	number	Index of the element in tabbing order.
items	any[]	An array of objects to display.
itemSize	any	The height/width of item according to orientation.
scrollHeight	string	Height of the scroll viewport.
scrollWidth	string	Width of the scroll viewport.
orientation	"both" \| "vertical" \| "horizontal"	The orientation of scrollbar.
step	number	Used to specify how many items to load in each load method in lazy mode.
delay	number	Delay in scroll before new data is loaded.
resizeDelay	number	Delay after window's resize finishes.
appendOnly	boolean	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.
inline	boolean	Specifies whether the scroller should be displayed inline or not.
lazy	boolean	Defines if data is loaded and interacted with in lazy manner.
disabled	boolean	If disabled, the scroller feature is eliminated and the content is displayed directly.
loaderDisabled	boolean	Used to implement a custom loader instead of using the loader feature in the scroller.
columns	any[]	Columns to display.
showSpacer	boolean	Used to implement a custom spacer instead of using the spacer feature in the scroller.
showLoader	boolean	Defines whether to show loader.
numToleratedItems	any	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. Default value is half the number of items shown in the view.
loading	boolean	Defines whether the data is loaded.
autoSize	boolean	Defines whether to dynamically change the height or width of scrollable container.
trackBy	Function	Function to optimize the dom operations by delegating to ngForTrackBy, default algoritm checks for object identity.
onLazyLoad	Function	Callback to invoke in lazy mode to load new data.
onScroll	Function	Callback to invoke when scroll position changes.
onScrollIndexChange	Function	Callback to invoke when scroll position and item's range in view changes.