Installation
$Terminal
npx shadcn@latest add https://sdk-components.thesqd.com/r/pagination.jsonUsage
Pass `page`, `totalPages`, and `onPageChange`. The component handles ellipsis generation and boundary disabling automatically.
TSImport
import { Pagination } from "@/components/ui/pagination";TSExample
import { useState } from "react";
import { Pagination } from "@/components/ui/pagination";
export function Example() {
const [page, setPage] = useState(1);
return (
<Pagination
page={page}
totalPages={20}
onPageChange={setPage}
/>
);
}Composition
Anatomy of the Pagination component.
Pagination (single component — pass page, totalPages, onPageChange)
├── page={number} (current 1-indexed page)
├── totalPages={number} (renders nothing when ≤ 1)
├── onPageChange={fn} (called with the new page number)
├── siblingCount={1} (neighbors around current page, default 1)
├── showPrevNext={true} (show Prev / Next buttons, default true)
├── previousLabel="Previous" (label for the Prev button)
├── nextLabel="Next" (label for the Next button)
└── size="default" | "sm" (sm = h-8 buttons, dense table footers)
Need router-aware links or a completely custom layout? The slot exports
(PaginationRoot / PaginationContent / PaginationItem / PaginationLink /
PaginationPrevious / PaginationNext / PaginationEllipsis) remain available
as an escape hatch from the same file.Default
Basic 10-page paginator. The current page is highlighted; Previous and Next are disabled at the boundaries.
Small
`size="sm"` shrinks the buttons and switches Prev / Next to icon-only. Used inside `DataGridPagination` for dense table footers.
Many pages
With 50 pages and `siblingCount={1}` (the default), ellipsis appears on both sides of the current page.
Few pages
When `totalPages` is small enough to show every page, no ellipsis is rendered.
Custom labels
Override the Prev / Next button text with `previousLabel` and `nextLabel`.
Wider sibling count
`siblingCount={2}` shows two neighbors on each side of the current page before collapsing to ellipsis.
API Reference
Props exposed by the Pagination component.
| Prop | Type | Default | Description |
|---|---|---|---|
page | number | — | Current 1-indexed page number. |
totalPages | number | — | Total number of pages. Renders nothing when ≤ 1. |
onPageChange | (page: number) => void | — | Callback with the new 1-indexed page when the user navigates. |
siblingCount | number | 1 | How many page-number buttons to show on each side of the current page. |
showPrevNext | boolean | true | Whether to render the Previous and Next buttons. |
previousLabel | string | "Previous" | Text label for the Previous button. |
nextLabel | string | "Next" | Text label for the Next button. |
size | "default" | "sm" | "default" | Visual size. `sm` shrinks all controls (h-8 icon-only Prev/Next, smaller ellipsis) for table footers and dense data grids. |
className | string | — | Class names forwarded to the outer <nav> element. |