Scroller is a performance-approach to handle huge data efficiently.
import { ScrollerModule } from 'primeng/scroller';
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>
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>
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>
Scrolling to a specific index can be done with the scrollToIndex function.
<p-button label="Reset" (click)="reset()"></p-button>
<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>
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>
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"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="50%" height="1.2rem"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="60%" height="1.2rem"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="50%" height="1.2rem"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="60%" height="1.2rem"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="50%" height="1.2rem"></p-skeleton></div>
<div class="flex align-items-center px-2" style="height: 25px"><p-skeleton width="60%" height="1.2rem"></p-skeleton></div>
</div>
</ng-template>
</p-scroller>
Scroll delay is adjusted by using delay property.
<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 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>
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>
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. |
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. 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 Scroller module.
Name | Type | Default | Description |
---|---|---|---|
id | string | null | Unique identifier of the element. |
style | object | null | Inline style of the component. |
styleClass | any | null | Style class of the component. |
tabindex | number | null | Index of the element in tabbing order. |
items | array | null | An array of objects to display. |
itemSize | number / [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 | string | 'vertical' | The orientation of scrollbar, valid values are 'vertical', 'horizontal' and 'both'. |
step | number | 0 | Used to specify how many items to load in each load method in lazy mode. |
delay | number | 0 | Delay in scroll before new data is loaded. |
resizeDelay | number | 10 | Delay after window's resize finishes. |
appendOnly | boolean | false | 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. |
lazy | boolean | false | Defines if data is loaded and interacted with in lazy manner. |
disabled | boolean | false | If disabled, the scroller feature is eliminated and the content is displayed directly. |
loaderDisabled | boolean | false | Used to implement a custom loader instead of using the loader feature in the scroller. |
loading | boolean | false | Whether the data is loaded. |
showSpacer | boolean | true | Used to implement a custom spacer instead of using the spacer feature in the scroller. |
showLoader | boolean | false | 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. |
autoSize | boolean | false | 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 | false | Whether to use the scroller feature. The properties of scroller component can be used like an object in it. |
Name | Parameters | Description |
---|---|---|
scrollTo | left: Left position of scroll. top: Top position of scroll behavior: Behavior of scroll, valid values are 'auto' and 'smooth' | Scroll to move to a specific position. |
scrollToIndex | index: Index of item according to orientation mode. behavior: Behavior of scroll, valid values are 'auto' and 'smooth' | Scroll to move to a specific item. |
scrollInView | index: Index of item according to orientation mode. to: Defines the location of the item in view, valid values are 'to-start' and 'to-end'. behavior: Behavior of scroll, valid values are 'auto' and 'smooth' | It is used to move the specified index into the view. It is a method that will usually be needed when keyboard support is added to the scroller component. |
getRenderedRange | - | Returns the range of items added to the DOM. |
getElementRef | - | Returns the reference of scroller container. |
Name | Parameters | Description |
---|---|---|
onScroll | event: Browser event | Callback to invoke when scroll position changes. |
onScrollIndexChange | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke when scroll position and item's range in view changes. |
onLazyLoad | event.first: First index of the new data range to be loaded. event.last: Last index of the new data range to be loaded. | Callback to invoke in lazy mode to load new data. |
Name | Parameters |
---|---|
content | - |
item | $implicit: Data of the option options: Options of the scroller |
loader | options: Options of the scroller on loading |
loadericon | options: Options of the scroller on loading |