Scroller

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

Import #


import { ScrollerModule } from 'primeng/scroller';

Basic #

Scroller 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-scroller 
    [items]="items" 
    [itemSize]="50" 
    scrollHeight="200px" 
    styleClass="border-1 surface-border" 
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div class="flex align-items-center p-2" [ngClass]="{ 'surface-ground': options.odd }" style="height: 50px;">
                {{ item }}
            </div>
        </ng-template>
</p-scroller>

Horizontal #

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


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

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-scroller 
    [items]="items" 
    [itemSize]="[50, 100]" 
    orientation="both" 
    styleClass="border-1 surface-border" 
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div 
                class="flex align-items-center p-2" 
                [ngClass]="{ 'surface-ground' : options.odd }" 
                style="height: 50px;">
                <div *ngFor="let el of item" style="width: 100px">
                    {{ el }}
                </div>
            </div>
        </ng-template>
</p-scroller>

Programmatic #

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


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

Loader #

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-scroller 
    [items]="items" 
    [itemSize]="50" 
    [showLoader]="true" 
    [delay]="250" 
    styleClass="border-1 surface-border" 
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div 
                class="flex align-items-center p-2" 
                [ngClass]="{ 'surface-ground' : options.odd }" 
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-scroller>

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-1 surface-border" 
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div class="flex flex-column align-items-strech" [ngClass]="{'surface-ground': options.odd}">
                <div class="flex align-items-center px-2" style="height: 25px">
                    Item: {{item}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    Index: {{options.index}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    Count: {{options.count}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    First: {{options.first}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    Last: {{options.last}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    Even: {{options.even}}
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    Odd: {{options.odd}}
                </div>
            </div>
        </ng-template>
        <ng-template pTemplate="loader" let-options="options">
            <div class="flex flex-column align-items-strech" [ngClass]="{'surface-ground': options.odd}">
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="50%" height="1.2rem" />
                </div>
                <div class="flex align-items-center px-2" style="height: 25px">
                    <p-skeleton width="60%" height="1.2rem" />
                </div>
            </div>
        </ng-template>
</p-scroller>

Delay #

Scroll delay is adjusted by using delay property.

No Delay

150ms

500ms


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

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

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

Lazy Load #

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-scroller 
    [items]="items" 
    [itemSize]="50" 
    [showLoader]="true" 
    [delay]="250" 
    [loading]="lazyLoading" 
    [lazy]="true" 
    (onLazyLoad)="onLazyLoad($event)" 
    styleClass="border-1 surface-border" 
    [style]="{'width': '200px', 'height': '200px'}">
        <ng-template pTemplate="item" let-item let-options="options">
            <div 
                class="flex align-items-center p-2" 
                [ngClass]="{ 'surface-ground': options.odd }" 
                style="height: 50px;">
                    {{ item }}
            </div>
        </ng-template>
</p-scroller>

Scroll Options #

The properties of scroller component can be used like an object in it.



<ng-template pTemplate="item" let-item let-scrollOptions="options">
    // item: Current item.
    // scrollOptions.index: Index of the item.
    // scrollOptions.count: Total numbers of items.
    // scrollOptions.first: Whether this is the first item.
    // scrollOptions.last: Whether this is the last item.
    // scrollOptions.even: Whether the index is even.
    // scrollOptions.odd: Whether the index is odd.
</ng-template>
<ng-template pTemplate="loader" let-scrollOptions="options">
    // scrollOptions.index: Index of the item.
    // scrollOptions.count: Total numbers of items.
    // scrollOptions.first: Whether this is the first item.
    // scrollOptions.last: Whether this is the last item.
    // scrollOptions.even: Whether the index is even.
    // scrollOptions.odd: Whether the index is odd.
    // scrollOptions.numCols: Total number of columns in a row in 'both' orientation mode in view.
</ng-template>
<ng-template pTemplate="loadericon" let-scrollOptions="options">
    // scrollOptions.styleClass: Style class of the default icon.
</ng-template>

Style #

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

Name	Element
p-scroller	Container element.
p-scroller-content	Content element.
p-scroller-loader	Loader element.

Accessibility #

Screen Reader

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

Scroller API

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

Scroller #

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

Properties #

Defines the input properties of the component.

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	"both" \| "vertical" \| "horizontal"	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.

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

Templates #

Defines the templates used by the component.

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.

Events #

Defines the custom events used by the component's emitters.

ScrollerLazyLoadEvent #

Custom lazy load event.

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

ScrollerScrollIndexChangeEvent #

Custom scroll index change event.

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

ScrollerScrollEvent #

Custom scroll event.

name	type	description
originalEvent	Event	Browser event.

Interfaces #

Defines the custom interfaces used by the module.

ScrollerContentOptions #

Scroller content options.

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

ScrollerItemOptions #

Scroller item options.

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.

ScrollerLoaderOptions #

Loader settings.

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.

Types #

Defines the custom types used by the module.

ScrollerToType #

values
"to-start" \| "to-end" \| undefined

ScrollerOrientationType #

values
"vertical" \| "horizontal" \| "both"

ScrollerLoaderIconOptions #

values
{"[klass:string]":"any"}