Paginator

An unstyled, accessible paginator component with compound composition.

Build fully custom paginators with complete control over layout, page rendering, and navigation styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Paginator with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with nine sub-components: Root, Content, First, Prev, Pages, Page, Ellipsis, Next, Last
Smart page range calculation with configurable siblings and edges
Automatic ellipsis insertion between page ranges
Render function children on Pages for full control over page item rendering

Usage#

import { Paginator } from 'primereact/paginator';

<Paginator.Root>
    <Paginator.Content>
        <Paginator.First></Paginator.First>
        <Paginator.Prev></Paginator.Prev>
        <Paginator.Pages></Paginator.Pages>
        <Paginator.Next></Paginator.Next>
        <Paginator.Last></Paginator.Last>
    </Paginator.Content>
</Paginator.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Paginator.Root as="div">
    <Paginator.Content as="section">
        <Paginator.First as="a" />
        <Paginator.Prev as="a" />
        <Paginator.Pages />
        <Paginator.Next as="a" />
        <Paginator.Last as="a" />
    </Paginator.Content>
</Paginator.Root>

Default elements: Root=nav, Content=div, First=button, Prev=button, Pages=span, Page=button, Ellipsis=span, Next=button, Last=button.

Render Function Children#

Pages accepts a render function as children, providing access to the component instance. The instance exposes paginator (root instance with pages array and state).

<Paginator.Pages>{(instance) => instance.paginator?.pages.map((page, i) => (page.type === 'page' ? <Paginator.Page key={i} value={page.value} /> : <Paginator.Ellipsis key={i}>...</Paginator.Ellipsis>))}</Paginator.Pages>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

PaginatorRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"root"`

Defines passthrough(pt) options of Paginator component.

label	type	description
root	PaginatorRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
content	PaginatorRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the content's DOM element.
first	PaginatorRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the first's DOM element.
prev	PaginatorRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the prev's DOM element.
next	PaginatorRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the next's DOM element.
last	PaginatorRootPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the last's DOM element.

PaginatorContent#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorContentInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorContentInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorContentInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorContentPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorContentInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of PaginatorContent component.

label	type	description
root	PaginatorContentPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorFirst#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorFirstInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorFirstInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorFirstInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorFirstPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorFirstInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`disabled`	`boolean`	—
Used to disable the first button.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"first"`
`data-disabled`	Present when disabled

Defines passthrough(pt) options of PaginatorFirst component.

label	type	description
root	PaginatorFirstPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorPrev#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorPrevInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorPrevInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorPrevInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorPrevPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorPrevInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`disabled`	`boolean`	—
Used to disable the previous button.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"prev"`
`data-disabled`	Present when disabled

Defines passthrough(pt) options of PaginatorPrev component.

label	type	description
root	PaginatorPrevPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorNext#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorNextInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorNextInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorNextInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorNextPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorNextInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`disabled`	`boolean`	—
Used to disable the next button.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"next"`
`data-disabled`	Present when disabled

Defines passthrough(pt) options of PaginatorNext component.

label	type	description
root	PaginatorNextPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorLast#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorLastInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorLastInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorLastInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorLastPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorLastInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`disabled`	`boolean`	—
Used to disable the last button.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"last"`
`data-disabled`	Present when disabled

Defines passthrough(pt) options of PaginatorLast component.

label	type	description
root	PaginatorLastPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorPages#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorPagesInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorPagesInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorPagesInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorPagesPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorPagesInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"pages"`

Defines passthrough(pt) options of PaginatorPages component.

label	type	description
root	PaginatorPagesPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

PaginatorPage#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorPageInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorPageInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorPageInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorPagePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorPageInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`disabled`	`boolean`	—
Used to disable the page button.
`value`	`number`	—
Used to set the value of the page button.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"paginator"`
`data-part`	`"page"`
`data-active`	Present on the current page
`data-disabled`	Present when disabled

Defines passthrough(pt) options of PaginatorPage component.

label	type	description
root	PaginatorPagePassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

PaginatorEllipsis#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PaginatorEllipsisInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PaginatorEllipsisInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PaginatorEllipsisInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PaginatorEllipsisPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PaginatorEllipsisInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of PaginatorEllipsis component.

label	type	description
root	PaginatorEllipsisPassThroughType<HTMLAttributes<HTMLButtonElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Paginator is placed inside a nav element to indicate a navigation section. First, previous, next, and last page navigator buttons include aria-label attributes derived from the aria.firstPageLabel, aria.prevPageLabel, aria.nextPageLabel, and aria.lastPageLabel locale properties respectively.

Page links are button elements with an aria-label derived from the aria.pageLabel locale property. The current page is marked with aria-current="page".

Keyboard Support#

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