# usePagination
> Turns a page and a page count into the list of pages and ellipses to render, keeping its length steady as the page moves.
Docs: https://hextaui.com/docs/use-pagination
Markdown: https://hextaui.com/docs/use-pagination.md
```tsx title="components/examples/use-pagination/demo.tsx"
"use client"
import * as React from "react"
import { IconChevronLeft, IconChevronRight } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
import { usePagination } from "@/hooks/use-pagination"
export function UsePaginationDemo() {
const [page, setPage] = React.useState(6)
const [siblings, setSiblings] = React.useState(1)
const pagination = usePagination({ page, count: 20, siblings })
return (
siblings
{
if (value[0]) {
setSiblings(Number(value[0]))
}
}}
>
012
{pagination.items.length} items
)
}
```
## Installation
### CLI
```bash
npx shadcn@latest add https://hextaui.com/r/use-pagination.json
```
This adds the hook and anything it depends on.
### Manual
Copy and paste the following code into your project.
```ts title="hooks/use-pagination.ts"
import * as React from "react"
type PaginationItemData =
| { type: "page"; page: number }
| { type: "ellipsis"; position: "start" | "end" }
type UsePaginationOptions = {
page?: number
count: number
siblings?: number
boundaries?: number
}
function clampInt(value: unknown, fallback: number, min: number, max: number) {
const number = Math.floor(Number(value))
if (!Number.isFinite(number)) {
return fallback
}
return Math.min(max, Math.max(min, number))
}
function range(start: number, end: number) {
const pages: number[] = []
for (let page = start; page <= end; page++) {
pages.push(page)
}
return pages
}
function usePagination({
page,
count,
siblings = 1,
boundaries = 1,
}: UsePaginationOptions) {
const total = clampInt(count, 0, 0, Number.MAX_SAFE_INTEGER)
const current = total === 0 ? 0 : clampInt(page, 1, 1, total)
const siblingCount = clampInt(siblings, 1, 0, 10)
const boundaryCount = clampInt(boundaries, 1, 0, 10)
const items = React.useMemo(() => {
if (total === 0) {
return []
}
const start = range(1, Math.min(boundaryCount, total))
const end = range(
Math.max(total - boundaryCount + 1, boundaryCount + 1),
total
)
const siblingsStart = Math.max(
Math.min(
current - siblingCount,
total - boundaryCount - siblingCount * 2 - 1
),
boundaryCount + 2
)
const siblingsEnd = Math.min(
Math.max(current + siblingCount, boundaryCount + siblingCount * 2 + 2),
end.length > 0 ? end[0] - 2 : total - 1
)
const pages: (number | "start" | "end")[] = [
...start,
...(siblingsStart > boundaryCount + 2
? (["start"] as const)
: boundaryCount + 1 < total - boundaryCount
? [boundaryCount + 1]
: []),
...range(siblingsStart, siblingsEnd),
...(siblingsEnd < total - boundaryCount - 1
? (["end"] as const)
: total - boundaryCount > boundaryCount
? [total - boundaryCount]
: []),
...end,
]
const seen = new Set()
return pages
.filter((item) => {
if (seen.has(item)) {
return false
}
seen.add(item)
return typeof item === "string" || (item >= 1 && item <= total)
})
.map((item) =>
typeof item === "string"
? { type: "ellipsis", position: item }
: { type: "page", page: item }
)
}, [total, current, siblingCount, boundaryCount])
return {
page: current,
count: total,
items,
hasPrevious: current > 1,
hasNext: current < total,
}
}
export { usePagination }
export type { PaginationItemData, UsePaginationOptions }
```
Update the import paths to match your project setup.
## Usage
```tsx
import { usePagination } from "@/hooks/use-pagination"
```
```tsx
const { items, page, hasPrevious, hasNext } = usePagination({
page: currentPage,
count: totalPages,
})
items.map((item) =>
item.type === "ellipsis" ? (
…
) : (
{item.page}
)
)
```
The hook only does the math. It returns the list of pages and ellipses to render and leaves the markup to you, which is how `Pagination` builds its links. Use it to build your own pager, like dots for a carousel or a page picker in a table footer.
## How it works
The list always shows the first and last `boundaries` pages, and `siblings` pages on each side of the current one. An ellipsis fills any gap of two pages or more. A gap of exactly one page shows that page instead, because an ellipsis there would hide no more than it takes up.
```bash
count: 20, siblings: 1, boundaries: 1
page 1 1 2 3 4 5 … 20
page 6 1 … 5 6 7 … 20
page 20 1 … 16 17 18 19 20
```
Once there are enough pages, the list always has `2 × boundaries + 2 × siblings + 3` items. Near the ends, the window widens instead of shrinking. Because the length never changes, the pager keeps its width, and the next and previous buttons stay under the pointer as you click through.
- `count` and `page` are clamped: a page past the end becomes the last page, and anything that isn't a finite number falls back to the default.
- A `count` of 0 returns no items and a `page` of 0, so an empty table can render nothing without a special case.
- `siblings` and `boundaries` go from 0 to 10.
- Ellipses have a stable `position` of `start` or `end`. Use it as the React key.
## Examples
### Dots
With `boundaries: 0` the list is just a window around the current page. Ellipses become small dots, so a long set of slides never needs more than five targets.
```tsx title="components/examples/use-pagination/dots.tsx"
"use client"
import * as React from "react"
import { usePagination } from "@/hooks/use-pagination"
export function UsePaginationDots() {
const [page, setPage] = React.useState(1)
const { items } = usePagination({
page,
count: 12,
siblings: 1,
boundaries: 0,
})
return (
)
}
```
## Good to know
- Mark the current page with `aria-current="page"` and wrap the list in a `