Scroller

VirtualScroller is a performance-approach to handle huge data efficiently.

Import #


import { Scroller } from 'primeng/scroller';

Basic #

VirtualScroller requires items as the data to display, itemSize for the dimensions of an item and item template are required on component. In addition, an initial array is required based on the total number of items to display. Size of the viewport is configured using scrollWidth, scrollHeight properties directly or with CSS width and height styles.


<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    scrollHeight="200px"
    styleClass="border border-surface"
    [style]="{ width: '200px', height: '200px' }"
>
    <ng-template pTemplate="item" let-item let-options="options">
        <div
            class="flex items-center p-2"
            [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
            style="height: 50px;"
        >
            {{ item }}
        </div>
    </ng-template>
</p-virtualscroller>

Horizontal #

Setting orientation to horizontal enables scrolling horizontally. In this case, the itemSize should refer to the width of an item.


<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    scrollHeight="200px"
    orientation="horizontal"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                style="writing-mode: vertical-lr; width: 50px;"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
            >
                {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

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.


<p-virtualscroller
    [items]="items"
    [itemSize]="[50, 100]"
    orientation="both"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700' : options.odd }"
                style="height: 50px;">
                <div *ngFor="let el of item" style="width: 100px">
                    {{ el }}
                </div>
            </div>
        </ng-template>
</p-virtualscroller>

Delay #

Scroll delay is adjusted by using delay property.

No Delay

150ms

500ms


<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    [delay]="150"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    [delay]="500"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

Loading #

Busy state is enabled by adding showLoader property which blocks the UI with a modal by default. Alternatively, loader template can be used to customize items e.g. with Skeleton.


<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    [showLoader]="true"
    [delay]="250"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700' : options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

Lazy #

Lazy mode is handy to deal with large datasets where instead of loading the entire data, small chunks of data are loaded on demand by invoking onLazyLoad callback everytime scrolling requires a new chunk. To implement lazy loading, enable lazy attribute, initialize your data as a placeholder with a length and finally implement a method callback using onLazyLoad that actually loads a chunk from a datasource. onLazyLoad gets an event object that contains information about the chunk of data to load such as the index and number of items to load. Notice that a new template called loadingItem is also required to display as a placeholder while the new items are being loaded.


<p-virtualscroller
    [items]="items"
    [itemSize]="50"
    [showLoader]="true"
    [delay]="250"
    [loading]="lazyLoading"
    [lazy]="true"
    (onLazyLoad)="onLazyLoad($event)"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

Programmatic #

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


<p-button label="Reset" (click)="reset()" />
<p-virtualscroller
    #sc
    [items]="items"
    [itemSize]="50"
    scrollHeight="200px"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div
                class="flex items-center p-2"
                [ngClass]="{ 'bg-surface-100 dark:bg-surface-700': options.odd }"
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-virtualscroller>

Template #

Scroller content is customizable by using ng-template. Valid values are content, item, loader and loadericon


<p-scroller
    class="custom-loading"
    [items]="items"
    [itemSize]="25 * 7"
    [showLoader]="true"
    [delay]="250"
    styleClass="border border-surface"
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template #item let-item let-options="options">
            <div class="flex flex-col align-items-strech" [ngClass]="{'surface-ground': options.odd}">
                <div class="flex items-center px-2" style="height: 25px">
                    Item: {{item}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    Index: {{options.index}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    Count: {{options.count}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    First: {{options.first}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    Last: {{options.last}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    Even: {{options.even}}
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    Odd: {{options.odd}}
                </div>
            </div>
        </ng-template>
        <ng-template #loader let-options="options">
            <div class="flex flex-col align-items-strech" [ngClass]="{'surface-ground': options.odd}">
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
            </div>
        </ng-template>
</p-scroller>

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.

Keyboard Support

Component does not include any built-in interactive elements.

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

name	parameters	description
onLazyLoad	event : ScrollerLazyLoadEvent	Callback to invoke in lazy mode to load new data.
onScroll	event : ScrollerScrollEvent	Callback to invoke when scroll position changes.
onScrollIndexChange	event : ScrollerScrollIndexChangeEvent	Callback to invoke when scroll position and item's range in view changes.

name	parameters	description
content	context : { $implicit: any, // Loaded items. options: ScrollerContentOptions, // undefined }	Custom content template.
item	context : { $implicit: any, // Item instance. options: ScrollerItemOptions, // Scroller item options. }	Custom item template.
loader	context : { options: ScrollerLoaderOptions, // Options. }	Custom loader template.
loadericon	context : { options: ScrollerLoaderIconOptions, // Options. }	Custom loader icon template.

name	type	description
first	number	First element index in viewport.
last	number	Last element index in viewport.

name	type	description
first	number	First element index in viewport.
last	number	Last element index in viewport.

Scroller

Import #

Basic #

Horizontal #

Grid #

Delay #

Loading #

Lazy #

Programmatic #

Template #

Accessibility #

Screen Reader

Keyboard Support

Scroller API

Scroller #

Properties #

Emitters #

Templates #

Events #

ScrollerLazyLoadEvent #

ScrollerScrollIndexChangeEvent #

ScrollerScrollEvent #

Interfaces #

ScrollerContentOptions #

ScrollerItemOptions #

ScrollerLoaderOptions #

Types #

ScrollerToType #

ScrollerOrientationType #

ScrollerLoaderIconOptions #

Scroller Theming

CSS Classes #

Scroller Design Tokens #

name	type	description
contentStyleClass	string
items	any[]
loading	boolean
itemSize	number
rows	any[]
columns	any[]
spacerStyle	Object
contentStyle	Object
vertical	boolean
horizontal	boolean
both	boolean
getItemOptions	Function
getLoaderOptions	Function

name	type	description
index	number	Index of the item.
count	number	Item count.
first	boolean	Index of the first element in viewport.
last	boolean	Index of the last element in viewport.
even	boolean	Defines if index is even number.
odd	boolean	Defines if index is odd number.

class	description
p-virtualscroller	Class name of the root element
p-virtualscroller-content	Class name of the content element
p-virtualscroller-spacer	Class name of the spacer element
p-virtualscroller-loader	Class name of the loader element
p-virtualscroller-loading-icon	Class name of the loading icon element

token	variable	description
virtualscroller.loader.mask.background	--p-virtualscroller-loader-mask-background	Background of loader mask
virtualscroller.loader.mask.color	--p-virtualscroller-loader-mask-color	Color of loader mask
virtualscroller.loader.icon.size	--p-virtualscroller-loader-icon-size	Size of the loader icon