Pagination

A navigation component that allows users to browse through pages.

Anatomy

<Pagination.Root>
  <Pagination.PrevTrigger />
  <Pagination.Item />
  <Pagination.Ellipsis />
  <Pagination.NextTrigger />
</Pagination.Root>

Examples

Controlled

To create a controlled Pagination component, manage the state of the current page using the page prop and update it when the onPageChange event handler is called:

Root Provider

An alternative way to control the pagination is to use the RootProvider component and the usePagination hook. This way you can access the state and methods from outside the component.

Customization

You can customize the Pagination component by setting various props such as dir, pageSize, siblingCount, and translations. Here's an example of a customized Pagination:

Context

The Context component provides access to the pagination state and methods through a render prop pattern. This allows you to access methods like setPage, setPageSize, goToNextPage, goToPrevPage, goToFirstPage, goToLastPage, as well as properties like totalPages and pageRange.

Data Slicing

Use the slice() method to paginate actual data arrays. This method automatically slices your data based on the current page and page size.

Page Range

Display the current page range information using the pageRange property. This shows which items are currently visible (e.g., "Showing 1-10 of 100 results").

Page Size

Control the number of items per page dynamically using setPageSize(). This example shows how to integrate a native select element to change the page size.

Note: For uncontrolled behavior, use defaultPageSize to set the initial value. For controlled behavior, use pageSize and onPageSizeChange to programmatically manage the page size.

Links

Create pagination with link navigation for better SEO and accessibility. This example shows how to use the pagination component with anchor links instead of buttons.

API Reference

Props

Root

Renders a <> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`count`		`number` Total number of data items
`defaultPage`	`1`	`number` The initial active page when rendered. Use when you don't need to control the active page of the pagination.
`defaultPageSize`	`10`	`number` The initial number of data items per page when rendered. Use when you don't need to control the page size of the pagination.
`getPageUrl`		`(details: PageUrlDetails) => string` Function to generate href attributes for pagination links. Only used when `type` is set to "link".
`ids`		`Partial<{ root: string ellipsis: (index: number) => string prevTrigger: string nextTrigger: string item: (page: number) => string }>` The ids of the elements in the accordion. Useful for composition.
`onPageChange`		`(details: PageChangeDetails) => void` Called when the page number is changed
`onPageSizeChange`		`(details: PageSizeChangeDetails) => void` Called when the page size is changed
`page`		`number` The controlled active page
`pageSize`		`number` The controlled number of data items per page
`siblingCount`	`1`	`number` Number of pages to show beside active page
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`type`	`'button'`	`'button' \| 'link'` The type of the trigger element

Ellipsis

Renders a <div> element.

Prop	Default	Type
`index`		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Item

Renders a <button> element.

Prop	Default	Type
`type`		`'page'`
`value`		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	pagination
`[data-part]`	item
`[data-index]`	The index of the item
`[data-selected]`	Present when selected

NextTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	pagination
`[data-part]`	next-trigger
`[data-disabled]`	Present when disabled

PrevTrigger

Renders a <button> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	pagination
`[data-part]`	prev-trigger
`[data-disabled]`	Present when disabled

RootProvider

Renders a <> element.

Prop	Default	Type
`value`		`UsePaginationReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`page`	`number` The current page.
`count`	`number` The total number of data items.
`pageSize`	`number` The number of data items per page.
`totalPages`	`number` The total number of pages.
`pages`	`Pages` The page range. Represented as an array of page numbers (including ellipsis)
`previousPage`	`number` The previous page.
`nextPage`	`number` The next page.
`pageRange`	`PageRange` The page range. Represented as an object with `start` and `end` properties.
`slice`	`<V>(data: V[]) => V[]` Function to slice an array of data based on the current page.
`setPageSize`	`(size: number) => void` Function to set the page size.
`setPage`	`(page: number) => void` Function to set the current page.
`goToNextPage`	`VoidFunction` Function to go to the next page.
`goToPrevPage`	`VoidFunction` Function to go to the previous page.
`goToFirstPage`	`VoidFunction` Function to go to the first page.
`goToLastPage`	`VoidFunction` Function to go to the last page.