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'

const Basic = () => (
  <Pagination.Root count={5000} pageSize={10} siblingCount={2}>
    {({ pages }) => (
      <>
        <Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
        {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.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 { Pagination } from '@ark-ui/react'
import { useState } from 'react'

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

  return (
    <Pagination.Root
      count={5000}
      pageSize={10}
      siblingCount={2}
      page={currentPage}
      onPageChange={(details) => setCurrentPage(details.page)}
    >
      {({ pages }) => (
        <>
          <Pagination.PrevTrigger>Previous</Pagination.PrevTrigger>
          {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.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'

const Customized = () => (
  <Pagination.Root
    count={5000}
    pageSize={20}
    siblingCount={3}
    dir="ltr"
    translations={{
      nextTriggerLabel: 'Next',
      prevTriggerLabel: 'Prev',
      itemLabel: (details) => `Page ${details.page}`,
    }}
  >
    {({ pages }) => (
      <>
        <Pagination.PrevTrigger>Previous</Pagination.PrevTrigger>
        {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.NextTrigger>Next Page</Pagination.NextTrigger>
      </>
    )}
  </Pagination.Root>
)

API Reference

Root

PropTypeDefault
count
number
asChild
boolean
defaultPage
number
dir
'ltr' | 'rtl'"ltr"
getRootNode
() => Node | ShadowRoot | Document
id
string
ids
Partial<{ root: string ellipsis(index: number): string prevTrigger: string nextTrigger: string item(page: number): string }>
onPageChange
(details: PageChangeDetails) => void
page
number
pageSize
number
siblingCount
number
translations
IntlTranslations
type
'link' | 'button'"button"

Item

PropTypeDefault
type
'page'
value
number
asChild
boolean

Ellipsis

PropTypeDefault
index
number
asChild
boolean

NextTrigger

PropTypeDefault
asChild
boolean

PrevTrigger

PropTypeDefault
asChild
boolean