# Pagination

URL: https://ark-ui.com/docs/components/pagination
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/pagination.mdx

A navigation component that allows users to browse through pages.

---

<ComponentPreview id="Pagination" />

## Anatomy

To set up the pagination correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="pagination" />

## Examples

Learn how to use the `Pagination` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Controlled Pagination

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:

<Example id="controlled" />

### Customizing Pagination

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:

<Example id="customized" />

### Using 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`.

<Example id="context" />

### 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.

<Example id="data-slicing" />

### Page Range Display

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").

<Example id="page-range" />

### Page Size Control

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.

<Example id="page-size-control" />

### Link Pagination

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.

<Example id="link" />

### Root Provider

The `RootProvider` component provides a context for the pagination. It accepts the value of the `usePagination` hook.
You can leverage it to access the component state and methods from outside the pagination.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | 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` | No | 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
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'button' | 'link'` | No | The type of the trigger element |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePaginationReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'nav'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | 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` | No | 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
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'link' | 'button'` | No | The type of the trigger element |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePaginationReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'nav'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | 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` | No | Function to generate href attributes for pagination links.
Only used when `type` is set to "link". |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  ellipsis(index: number): string
  prevTrigger: string
  nextTrigger: string
  item(page: number): string
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'button' | 'link'` | No | The type of the trigger element |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

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


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `PaginationApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'nav'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | 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` | No | Function to generate href attributes for pagination links.
Only used when `type` is set to "link". |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  ellipsis: (index: number) => string
  prevTrigger: string
  nextTrigger: string
  item: (page: number) => string
}>` | No | The ids of the elements in the accordion. Useful for composition. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `ref` | `Element` | No |  |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'button' | 'link'` | No | The type of the trigger element |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UsePaginationContext]>` | Yes |  |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Item Data Attributes:**

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


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePaginationReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'nav'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


### Context

These are the properties available when using `Pagination.Context`, `usePaginationContext` hook or `usePagination` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `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. |