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
Footer 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.

NameElement
p-virtualscrollerContainer element.
p-virtualscroller-headerHeader section.
p-virtualscroller-footerFooter section.
p-virtualscroller-contentContent section.
p-virtualscroller-listList element.
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.

PrimeNG 16.0.0-rc.2 by PrimeTek