Paginator

Paginator displays data in paged format and provides navigation between pages.

Import #


import { PaginatorModule } from 'primeng/paginator';

Basic #

Paginator is used as a controlled component with first, rows and onPageChange properties to manage the first index and number of records to display per page. Total number of records need to be with totalRecords property. Default template includes a dropdown to change the rows so rowsPerPageOptions is also necessary for the dropdown options.



<p-paginator (onPageChange)="onPageChange($event)" [first]="first" [rows]="rows" [totalRecords]="120" [rowsPerPageOptions]="[10, 20, 30]"></p-paginator>

Locale #

Localization information such as page numbers and rows per page options are defined with the locale property which defaults to the user locale.

User Locale

United States Locale

Persian Locale



<div class="flex-auto">
    <p-paginator (onPageChange)="onPageChange($event)" [first]="first" [rows]="rows" [totalRecords]="120" [rowsPerPageOptions]="[10, 20, 30]"></p-paginator>
</div>
<div class="flex-auto">
    <p-paginator locale="en-US" (onPageChange)="onPageChange($event)" [first]="first" [rows]="rows" [totalRecords]="120" [rowsPerPageOptions]="[10, 20, 30]"></p-paginator>
</div>
<div class="flex-auto">
    <p-paginator locale="fa-IR" (onPageChange)="onPageChange($event)" [first]="first" [rows]="rows" [totalRecords]="120" [rowsPerPageOptions]="[10, 20, 30]"></p-paginator>
</div>

Template #

Templating allows overriding the default content of the UI elements by defining callbacks using the element name.

Items per page:

1 - 10 of 120

Items per page:

1 - 10 of 120



<div class="flex align-items-center justify-content-center">
    <div>
        <p-button icon="pi pi-star" styleClass="p-button-outlined"></p-button>
    </div>
    <div class="flex-1">
        <p-paginator (onPageChange)="onPageChange1($event)" [first]="first1" [rows]="rows1" [totalRecords]="120" [rowsPerPageOptions]="[10, 20, 30]" [showFirstLastIcon]="false"></p-paginator>
    </div>
    <div class="justify-content-end">
        <p-button icon="pi pi-search"></p-button>
    </div>
</div>

<div class="flex align-items-center justify-content-end">
    <span class="mx-1 text-color">Items per page: </span>
    <p-dropdown [options]="options" optionLabel="label" optionValue="value" [(ngModel)]="rows2" (ngModelChange)="first2 = 0"></p-dropdown>
    <p-paginator [first]="first2" [rows]="rows2" [totalRecords]="120" (onPageChange)="onPageChange2($event)" [showCurrentPageReport]="true"
        currentPageReportTemplate="{first} - {last} of {totalRecords}" [showPageLinks]="false" [showFirstLastIcon]="false" ></p-paginator>
</div>

<div class="flex align-items-center justify-content-start">
    <div class="flex justify-content-center align-items-center gap-3">
        <span>Items per page: </span>
        <p-slider [(ngModel)]="rows3" (ngModelChange)="first3 = 0" [style]="{ width: '10rem' }" [min]="10" [max]="120" [step]="30"></p-slider>
    </div>
    <p-paginator (onPageChange)="onPageChange3($event)" [first]="first3" [rows]="rows3" [totalRecords]="totalRecords" [showFirstLastIcon]="false" 
        [showCurrentPageReport]="true" currentPageReportTemplate="{first} - {last} of {totalRecords}" ></p-paginator>
</div>

Images #

Sample image gallery implementation using paginator.



<p-paginator [first]="first" [rows]="1" [totalRecords]="120" (onPageChange)="onPageChange($event)" [showJumpToPageDropdown]="true" [showPageLinks]="false"></p-paginator>
<img src="https://primefaces.org/cdn/primeng/images/demo/nature/nature{{ first + 1 }}.jpg" class="max-w-full"/>

Style #

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

Name	Element
p-paginator	Container element.
p-paginator-first	First page element.
p-paginator-prev	Previous page element.
p-paginator-pages	Container of page links.
p-paginator-page	A page link.
p-paginator-next	Next page element.
p-paginator-last	Last page element.
p-paginator-rpp-options	Rows per page dropdown.
p-paginator-page-options	Jump to per page dropdown.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility #

Screen Reader

Paginator is placed inside a nav element to indicate a navigation section. All of the paginator elements can be customized using templating however the default behavious is listed below.

First, previous, next and last page navigators elements with aria-label attributes referring to the aria.firstPageLabel, aria.prevPageLabel, aria.nextPageLabel and aria.lastPageLabelproperties of the locale API respectively.

Page links are also button elements with an aria-label attribute derived from the aria.pageLabel of the locale API. Current page is marked with aria-current set to "page" as well.

Current page report uses aria-live="polite" to instruct screen reader about the changes to the pagination state.

Rows per page dropdown internally uses a dropdown component, refer to the dropdown documentation for accessibility details. Additionally, the dropdown uses an aria-labelfrom the aria.rowsPerPage property of the locale API.

Jump to page input is an input element with an aria-label that refers to the aria.jumpToPage property of the locale API.

Keyboard Support

Key	Function
tab	Moves focus through the paginator elements.
enter	Executes the paginator element action.
space	Executes the paginator element action.

Rows Per Page Dropdown Keyboard Support

Refer to the dropdown documentation for more details about keyboard support.

Paginator API

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

Paginator #

Paginator is a generic component to display content in paged format.

Properties #

Defines the input properties of the component.

name	type	default	description
pageLinkSize	number	5	Number of page links to display.
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
alwaysShow	boolean	true	Whether to show it even there is only one page.
dropdownAppendTo	any	null	Target element to attach the dropdown overlay, valid values are "body" or a local ng-template variable of another element (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name).
templateLeft	TemplateRef<PaginatorState>	null	Template instance to inject into the left side of the paginator.
templateRight	TemplateRef<PaginatorState>	null	Template instance to inject into the right side of the paginator.
appendTo	any	null	Target element to attach the dropdown overlay, valid values are "body" or a local ng-template variable of another element (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having #mydiv as variable name).
dropdownScrollHeight	string	200px	Dropdown height of the viewport in pixels, a scrollbar is defined if height of list exceeds this value.
currentPageReportTemplate	string	{currentPage} of {totalPages}	Template of the current page report element. Available placeholders are {currentPage},{totalPages},{rows},{first},{last} and {totalRecords}
showCurrentPageReport	boolean	false	Whether to display current page report.
showFirstLastIcon	boolean	true	When enabled, icons are displayed on paginator to go first and last page.
totalRecords	number	0	Number of total records.
rows	number	0	Data count to display per page.
rowsPerPageOptions	any[]	null	Array of integer/object values to display inside rows per page dropdown. A object that have 'showAll' key can be added to it to show all data. Exp; [10,20,30,{showAll:'All'}]
showJumpToPageDropdown	boolean	false	Whether to display a dropdown to navigate to any page.
showJumpToPageInput	boolean	false	Whether to display a input to navigate to any page.
showPageLinks	boolean	true	Whether to show page links.
locale	string	null	Locale to be used in formatting.
dropdownItemTemplate	TemplateRef<Object>	null	Template instance to inject into the dropdown item inside in the paginator.
first	number	null	Zero-relative number of the first row to be displayed.

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
onPageChange	value : PaginatorState	Callback to invoke when page changes, the event object contains information about the new state.

Templates #

Defines the templates used by the component.

name	parameters	description
firstpagelinkicon	-	Custom first page link icon template.
previouspagelinkicon	-	Custom previous page link icon template.
lastpagelinkicon	-	Custom last page link icon template.
nextpagelinkicon	-	Custom next page link icon template.

Interfaces #

Defines the custom interfaces used by the module.

PaginatorState #

Paginator state.

name	type	description
page	number
first	number
rows	number
pageCount	number