usePaginator

Hook that manages pagination state, page calculations, and accessible navigation prop objects.

basic-demo

Usage#

import { usePaginator } from '@primereact/headless/paginator';
 
const paginator = usePaginator({ total: 100, itemsPerPage: 10 });
 
return (
    <nav {...paginator.rootProps}>
        <button {...paginator.firstProps}></button>
        <button {...paginator.prevProps}></button>
        <span {...paginator.pagesProps}>
            {paginator.pages.map((page, i) => (
                <button key={i} {...paginator.getPageProps(page.value!)}></button>
            ))}
        </span>
        <button {...paginator.nextProps}></button>
        <button {...paginator.lastProps}></button>
    </nav>
);

usePaginator computes page ranges, ellipsis positions, and pre-built ARIA props for navigation buttons — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects (rootProps, firstProps, prevProps, nextProps, lastProps, pagesProps, getPageProps)
Smart page range algorithm with configurable siblings and edges
Automatic ellipsis insertion with showEllipsis toggle
Exposes state.activePage, state.totalPages, state.canPrev, state.canNext for custom rendering

Behavior#

Default Page#

Use defaultPage to set the initial active page in uncontrolled mode.

const paginator = usePaginator({ defaultPage: 3, total: 100, itemsPerPage: 10 });

Controlled#

Use page and onPageChange for full programmatic control.

const [page, setPage] = React.useState(1);
const paginator = usePaginator({
    page,
    total: 100,
    itemsPerPage: 10,
    onPageChange: (e) => setPage(e.value)
});

Items Per Page#

Set itemsPerPage to control how many items each page represents. Total pages are computed as Math.ceil(total / itemsPerPage).

const paginator = usePaginator({ total: 200, itemsPerPage: 20 });

Siblings#

Set siblings to control the number of page buttons shown on each side of the active page.

const paginator = usePaginator({ total: 100, itemsPerPage: 5, siblings: 2 });

Edges#

Set edges to control how many page buttons are always visible at the start and end of the range.

const paginator = usePaginator({ total: 100, itemsPerPage: 5, edges: 2 });

Show Ellipsis#

Set showEllipsis to false to hide the gap indicators between page ranges. When disabled, edges is ignored.

const paginator = usePaginator({ total: 100, itemsPerPage: 5, showEllipsis: false });

Disabled#

Set disabled to prevent all navigation interaction.

const paginator = usePaginator({ total: 100, itemsPerPage: 10, disabled: true });

Rendering Pages and Ellipsis#

The pages array contains items with type of 'page' or 'ellipsis'. Iterate over it to render page buttons and gap indicators.

const paginator = usePaginator({ total: 100, itemsPerPage: 5 });
 
paginator.pages.map((item, i) =>
    item.type === 'page' ? (
        <button key={i} {...paginator.getPageProps(item.value!)}>
            {item.value}
        </button>
    ) : (
        <span key={i}>...</span>
    )
);

Custom Styling with Data Attributes#

Prop objects include data attributes for styling active, disabled, and navigation states.

[data-active] {
    background: var(--p-primary-color);
    color: var(--p-primary-contrast-color);
}
 
[data-disabled] {
    opacity: 0.5;
    pointer-events: none;
}

Using `state` for Custom UI#

The hook exposes reactive state for rendering custom indicators or text.

const paginator = usePaginator({ total: 100, itemsPerPage: 10 });
 
<span>
    Page {paginator.state.activePage} of {paginator.state.totalPages}
</span>;

API#

usePaginator#

Name	Type	Default
`defaultPage`	`number`	`1`
Default page number.
`page`	`number`	—
Current page number (controlled).
`total`	`number`	`0`
Total number of items.
`itemsPerPage`	`number`	`10`
Number of items per page.
`onPageChange`	`(event: usePaginatorChangeEvent) => void`	—
Callback fired when the page changes.
`siblings`	`number`	`2`
Number of sibling pages to show on each side of current page.
`edges`	`number`	`1`
Number of edge pages to show at the beginning and end.
`disabled`	`boolean`	`false`
Whether the paginator is disabled.
`showEllipsis`	`boolean`	`true`
Whether to show ellipsis.

Accessibility#

See Paginator Primitive for WAI-ARIA compliance details and keyboard support.