VirtualScroller is a performant approach to render large amounts of data efficiently.
import { VirtualScrollerModule } from 'primeng/virtualscroller';
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>
Header and Footer are the two sections that are capable of displaying custom content by using header and footer templates.
<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 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.
<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>
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>
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. |
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.
API defines helper props, events and others for the PrimeNG VirtualScroller module.
Name | Type | Default | Description |
---|---|---|---|
delay | number | 250 | Threshold in milliseconds to delay lazy loading during scrolling. |
itemSize | number | null | Height of an item in the list. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
scrollHeight | any | null | Max height of the content area in inline mode. |
style | string | null | Inline style of the component. |
styleClass | string | null | Style class of the component. |
value | array | null | An array of objects to display. |
options | ScrollerOptions | false | Whether to use the scroller feature. The properties of scroller component can be used like an object in it. |
Name | Parameters | Description |
---|---|---|
onLazyLoad | event.first = First row offset event.last = Last row offset event.rows = Number of rows per page | Callback to invoke in lazy mode to load new data. |
Name | Parameters | Description |
---|---|---|
scrollToIndex | index: Index of the item. mode: Scroll mode e.g. 'auto' or 'smooth' | Scrolls to the item with the given index. |
Following is the list of structural style classes, for theming classes visit theming page.
Name | Parameters |
---|---|
header | - |
item | $implicit: Data of the option index: Index of the option count: Count of the options first: First row offset last: Last row offset |
loadingItem | $implicit: Data of the option index: Index of the option count: Count of the options first: First row offset last: Last row offset |
footer | - |