Pagination | Ark UI

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

import { Pagination } from '@ark-ui/solid'
import { For } from 'solid-js'

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

<script setup lang="ts">
import { Pagination } from '@ark-ui/vue'
</script>

<template>
  <Pagination.Root v-slot="{ pages }" :count="5000" :page-size="10" :sibling-count="2">
    <Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
    <template v-for="(page, index) in pages">
      <Pagination.Item v-if="page.type === 'page'" :key="page" :value="page.value">
        {{ page.value }}
      </Pagination.Item>
      <Pagination.Ellipsis v-else :key="index" :index="index"> &#8230; </Pagination.Ellipsis>
    </template>
    <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
  </Pagination.Root>
</template>

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>
  )
}

import { Pagination } from '@ark-ui/solid'
import { For, createSignal } from 'solid-js'

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

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

Story not available

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

import { Pagination } from '@ark-ui/solid'
import { For } from 'solid-js'

const Customized = () => {
  return (
    <Pagination.Root
      count={5000}
      pageSize={20}
      siblingCount={3}
      dir="ltr"
      translations={{
        nextTriggerLabel: 'Next',
        prevTriggerLabel: 'Prev',
        itemLabel: (details) => `Page ${details.page}`,
      }}
    >
      {(api) => (
        <>
          <Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
          <For each={api().pages}>
            {(page, index) =>
              page.type === 'page' ? (
                <Pagination.Item {...page}>{page.value}</Pagination.Item>
              ) : (
                <Pagination.Ellipsis index={index()}>&#8230;</Pagination.Ellipsis>
              )
            }
          </For>
          <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
        </>
      )}
    </Pagination.Root>
  )
}

<script setup lang="ts">
import { Pagination } from '@ark-ui/vue'
</script>

<template>
  <Pagination.Root
    v-slot="{ pages }"
    :count="5000"
    :page-size="20"
    :sibling-count="3"
    dir="ltr"
    :translations="{
      nextTriggerLabel: 'Next',
      prevTriggerLabel: 'Prev',
      itemLabel: (details) => `Page ${details.page}`,
    }"
  >
    <Pagination.PrevTrigger>Previous</Pagination.PrevTrigger>
    <template v-for="(page, index) in pages">
      <Pagination.Item v-if="page.type === 'page'" :key="page" :value="page.value">
        {{ page.value }}
      </Pagination.Item>
      <Pagination.Ellipsis v-else :key="index" :index="index"> &#8230; </Pagination.Ellipsis>
    </template>
    <Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
  </Pagination.Root>
</template>

API Reference

Item

Prop	Type	Default
`type`	`'page'`
`value`	`number`
`asChild`	`boolean`

Root

Prop	Type	Default
`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"`

Ellipsis

Prop	Type	Default
`index`	`number`
`asChild`	`boolean`

NextTrigger

Prop	Type	Default
`asChild`	`boolean`

PrevTrigger

Prop	Type	Default
`asChild`	`boolean`