Ark Logo

Pagination

A navigation component that allows users to browse through pages.

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.

Examples

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

import { Pagination } from '@ark-ui/react'

export const Basic = () => (
  <Pagination.Root count={5000} pageSize={10} siblingCount={2}>
    <Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
    <Pagination.Context>
      {(pagination) =>
        pagination.pages.map((page, index) =>
          page.type === 'page' ? (
            <Pagination.Item key={index} {...page}>
              {page.value}
            </Pagination.Item>
          ) : (
            <Pagination.Ellipsis key={index} index={index}>
              &#8230;
            </Pagination.Ellipsis>
          ),
        )
      }
    </Pagination.Context>
    <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
  </Pagination.Root>
)

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:

import { useState } from 'react'
import { Pagination } from '@ark-ui/react'

export const Controlled = () => {
  const [currentPage, setCurrentPage] = useState(1)

  return (
    <Pagination.Root
      count={5000}
      pageSize={10}
      siblingCount={2}
      page={currentPage}
      onPageChange={(details) => setCurrentPage(details.page)}
    >
      <Pagination.PrevTrigger>Previous</Pagination.PrevTrigger>
      <Pagination.Context>
        {(pagination) =>
          pagination.pages.map((page, index) =>
            page.type === 'page' ? (
              <Pagination.Item key={index} {...page}>
                {page.value}
              </Pagination.Item>
            ) : (
              <Pagination.Ellipsis key={index} index={index}>
                &#8230;
              </Pagination.Ellipsis>
            ),
          )
        }
      </Pagination.Context>
      <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
    </Pagination.Root>
  )
}

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:

import { Pagination } from '@ark-ui/react'

export const Customized = () => (
  <Pagination.Root
    count={5000}
    pageSize={20}
    siblingCount={3}
    translations={{
      nextTriggerLabel: 'Next',
      prevTriggerLabel: 'Prev',
      itemLabel: (details) => `Page ${details.page}`,
    }}
  >
    <Pagination.PrevTrigger>Previous</Pagination.PrevTrigger>
    <Pagination.Context>
      {(pagination) =>
        pagination.pages.map((page, index) =>
          page.type === 'page' ? (
            <Pagination.Item key={index} {...page}>
              {page.value}
            </Pagination.Item>
          ) : (
            <Pagination.Ellipsis key={index} index={index}>
              &#8230;
            </Pagination.Ellipsis>
          ),
        )
      }
    </Pagination.Context>
    <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
  </Pagination.Root>
)

API Reference

Root

PropDefaultType
count
number

Total number of data items

asChild
boolean

Render as a different element type.

defaultPage
number

The initial page of the pagination when it is first rendered. Use when you do not need to control the state of the pagination.

id
string

The unique identifier of the machine.

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, and it takes the resulting page number argument

page
number

The active page

pageSize
number

Number of data items per page

siblingCount
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

PropDefaultType
index
number

asChild
boolean

Render as a different element type.

Item

PropDefaultType
type
'page'

value
number

asChild
boolean

Render as a different element type.

NextTrigger

PropDefaultType
asChild
boolean

Render as a different element type.

PrevTrigger

PropDefaultType
asChild
boolean

Render as a different element type.