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-partattribute 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}>
…
</Pagination.Ellipsis>
),
)
}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
import { For } from 'solid-js'
import { Pagination } from '@ark-ui/solid'
export const Basic = () => (
<Pagination.Root count={5000} pageSize={10} siblingCount={2}>
<Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
<Pagination.Context>
{(api) => (
<For each={api().pages}>
{(page, index) =>
page.type === 'page' ? (
<Pagination.Item {...page}>{page.value}</Pagination.Item>
) : (
<Pagination.Ellipsis index={index()}>…</Pagination.Ellipsis>
)
}
</For>
)}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
<script setup lang="ts">
import { Pagination } from '@ark-ui/vue'
</script>
<template>
<Pagination.Root :count="100" :page-size="10" :sibling-count="2">
<Pagination.PrevTrigger>
Previous
<span className="visually-hidden">Page</span>
</Pagination.PrevTrigger>
<Pagination.Context v-slot="pagination">
<template v-for="(page, index) in pagination.pages">
<Pagination.Item
v-if="page.type === 'page'"
:key="index"
:value="page.value"
:type="page.type"
>
{{ page.value }}
</Pagination.Item>
<Pagination.Ellipsis v-else :key="'e' + index" :index="index">…</Pagination.Ellipsis>
</template>
</Pagination.Context>
<Pagination.NextTrigger>
Next
<span className="visually-hidden">Page</span>
</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 { 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}>
…
</Pagination.Ellipsis>
),
)
}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
}
import { For, createSignal } from 'solid-js'
import { Pagination } from '@ark-ui/solid'
export const Controlled = () => {
const [currentPage, setCurrentPage] = createSignal(1)
return (
<Pagination.Root
count={5000}
pageSize={10}
siblingCount={2}
page={currentPage()}
onPageChange={(details) => setCurrentPage(details.page)}
>
<Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
<Pagination.Context>
{(api) => (
<For each={api().pages}>
{(page, index) =>
page.type === 'page' ? (
<Pagination.Item {...page}>{page.value}</Pagination.Item>
) : (
<Pagination.Ellipsis index={index()}>…</Pagination.Ellipsis>
)
}
</For>
)}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
}
Story not foundCustomizing 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}>
…
</Pagination.Ellipsis>
),
)
}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
import { For } from 'solid-js'
import { Pagination } from '@ark-ui/solid'
export const Customized = () => {
return (
<Pagination.Root
count={5000}
pageSize={20}
siblingCount={3}
translations={{
nextTriggerLabel: 'Next',
prevTriggerLabel: 'Prev',
itemLabel: (details) => `Page ${details.page}`,
}}
>
<Pagination.PrevTrigger>Previous Page</Pagination.PrevTrigger>
<Pagination.Context>
{(api) => (
<For each={api().pages}>
{(page, index) =>
page.type === 'page' ? (
<Pagination.Item {...page}>{page.value}</Pagination.Item>
) : (
<Pagination.Ellipsis index={index()}>…</Pagination.Ellipsis>
)
}
</For>
)}
</Pagination.Context>
<Pagination.NextTrigger>Next Page</Pagination.NextTrigger>
</Pagination.Root>
)
}
<script setup lang="ts">
import { Pagination } from '@ark-ui/vue'
</script>
<template>
<Pagination.Root
:count="5000"
:page-size="20"
:sibling-count="3"
:translations="{
nextTriggerLabel: 'Next',
prevTriggerLabel: 'Prev',
itemLabel: (details) => `Page ${details.page}`,
}"
>
<Pagination.PrevTrigger>
Previous
<span className="visually-hidden">Page</span>
</Pagination.PrevTrigger>
<Pagination.Context v-slot="pagination">
<template v-for="(page, index) in pagination.pages">
<Pagination.Item
v-if="page.type === 'page'"
:key="index"
:value="page.value"
:type="page.type"
>
{{ page.value }}
</Pagination.Item>
<Pagination.Ellipsis v-else :key="'e' + index" :index="index">…</Pagination.Ellipsis>
</template>
</Pagination.Context>
<Pagination.NextTrigger>
Next
<span className="visually-hidden">Page</span>
</Pagination.NextTrigger>
</Pagination.Root>
</template>
API Reference
Root
| Prop | Type | Default |
|---|---|---|
countTotal number of data items | number | |
asChildRender as a different element type. | boolean | |
defaultPageThe initial page of the pagination. | number | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the accordion. Useful for composition. | Partial<{
root: string
ellipsis(index: number): string
prevTrigger: string
nextTrigger: string
item(page: number): string
}> | |
onPageChangeCalled when the page number is changed, and it takes the resulting page number argument | (details: PageChangeDetails) => void | |
pageThe active page | number | |
pageSizeNumber of data items per page | number | |
siblingCountNumber of pages to show beside active page | number | |
translationsSpecifies the localized strings that identifies the accessibility elements and their states | IntlTranslations | |
typeThe type of the trigger element | 'button' | 'link' | "button" |
Ellipsis
| Prop | Type | Default |
|---|---|---|
index | number | |
asChildRender as a different element type. | boolean |
Item
| Prop | Type | Default |
|---|---|---|
type | 'page' | |
value | number | |
asChildRender as a different element type. | boolean |
NextTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
PrevTrigger
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Previous
Number InputNext
Pin Input