Pagination

Enables navigation between pages of content with previous, next, and numbered controls.

Installation
$Terminal
npx shadcn@latest add https://sdk-components.thesqd.com/r/pagination.json
Usage
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.
PropTypeDefaultDescription
pagenumberCurrent 1-indexed page number.
totalPagesnumberTotal number of pages. Renders nothing when ≤ 1.
onPageChange(page: number) => voidCallback with the new 1-indexed page when the user navigates.
siblingCountnumber1How many page-number buttons to show on each side of the current page.
showPrevNextbooleantrueWhether to render the Previous and Next buttons.
previousLabelstring"Previous"Text label for the Previous button.
nextLabelstring"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.
classNamestringClass names forwarded to the outer <nav> element.