Pagination
Compact page navigation control with clamped prev and next actions plus ellipsis-based range collapsing for longer result sets.
AccessibleDark Mode
Install
$
npx react-principles add pagination01
Live Demo
Current page: 5
02
Code Snippet
src/ui/Pagination.tsx
import { Pagination } from "@/ui/Pagination"; <Pagination page={page} totalPages={12} onPageChange={setPage} siblingCount={1} />
03
Copy-Paste (Single File)
Pagination.tsx
import { cn } from "@/lib/utils"; type PaginationToken = number | "ellipsis"; export interface PaginationProps { page: number; totalPages: number; onPageChange: (page: number) => void; siblingCount?: number; className?: string; } function buildRange(page: number, totalPages: number, siblingCount: number): PaginationToken[] { const pages: PaginationToken[] = []; const totalButtons = siblingCount * 2 + 5; if (totalPages <= totalButtons) { for (let i = 1; i <= totalPages; i += 1) pages.push(i); return pages; } const leftSibling = Math.max(page - siblingCount, 1); const rightSibling = Math.min(page + siblingCount, totalPages); const showLeftEllipsis = leftSibling > 2; const showRightEllipsis = rightSibling < totalPages - 1; pages.push(1); if (showLeftEllipsis) { pages.push("ellipsis"); } else { for (let i = 2; i < leftSibling; i += 1) pages.push(i); } for (let i = leftSibling; i <= rightSibling; i += 1) { if (i !== 1 && i !== totalPages) pages.push(i); } if (showRightEllipsis) { pages.push("ellipsis"); } else { for (let i = rightSibling + 1; i < totalPages; i += 1) pages.push(i); } if (totalPages > 1) pages.push(totalPages); return pages; }
04
Props
| Prop | Type | Default | Description |
|---|---|---|---|
page | number | — | Current active page number. |
totalPages | number | — | Total number of pages available in the range. |
onPageChange | (page: number) => void | — | Called when users move to the previous, next, or a numbered page. |
siblingCount | number | 1 | Controls how many pages remain visible on either side of the current page. |
className | string | — | Additional classes applied to the pagination nav wrapper. |