Pagination
A complex navigation component that intelligently handles page rendering, ellipsis calculation, and edge bounds.
Building pagination logic from scratch is notoriously difficult. If you have 100 pages, you can't render 100 buttons. This
PaginationBlock automatically calculates the optimal view (e.g., 1, 2, ..., 4, 5, 6, ..., 100) based on the current active page, the total number of pages, and your specified sibling count. It also seamlessly disables the "Next" and "Previous" controls when you hit the edges.Click through the page numbers in each preview to watch the ellipses shift.
Pagination
Hold currentPage yourself and update it from onPageChange.
currentPage- and
totalPagesare both required — the component holds no state of its own. onPageChange- returns the target page number from a number click or the prev/next buttons.
Installation
New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.
Install Pagination
components/ is written into your project. Copy any snippet from a Usage tab above and it runs.
Install dependencies
Nothing beyond the shared setup — Pagination needs only the cn helper and lucide-react, which the installation guide already put in place.
Examples
Sibling count
siblingCount{2}- is how many numbers flank the active page before an ellipsis. Raise it for wide desktop layouts.
Jump to page & rows per page
Both controls are opt-in booleans; the page-size dropdown reports through onPageSizeChange.
showPageJump- adds a number input — type a page and press Enter, tab away, or hit Go. Out-of-range values clamp to the edges.
showPageSize- adds a rows-per-page dropdown. Pass
pageSize,pageSizeOptionsandonPageSizeChange, then re-derivetotalPages.
Dropdown page picker
pageJumpVariant"select"- swaps the free-typed input for a dropdown that lists every page — handy for smaller page counts.
In a data table
totalPages- is yours to derive —
Math.ceil(rows.length / pageSize)— and pairs naturally with a range readout.
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
currentPage | number | Required | The currently active page number. Drives the active state styling and
ellipsis calculation. |
totalPages | number | Required | The absolute total number of pages available in your dataset. |
onPageChange | (page: number) => void | undefined | Callback function fired when a user clicks a page number, or the
next/previous buttons. It returns the new target page number. |
siblingCount | number | 2 | Determines how many page buttons to show on either side of the
currentPage before rendering an ellipsis. Increase this
for wider desktop screens. |
showEdges | boolean | true | If true, renders the "Previous" and "Next" control buttons on the
extreme left and right of the pagination block. |
showPageJump | boolean | false | Shows a "Go to page" control. Values outside
1..totalPages are clamped before
onPageChange fires. |
pageJumpVariant | "input" | "select" | "input" | "input" is a number field with a Go button;
"select" is a dropdown listing every page. |
showPageSize | boolean | false | Shows a "Rows per page" dropdown. Requires pageSize and
onPageSizeChange. |
pageSize | number | 10 | The currently selected rows-per-page value. If it isn't in
pageSizeOptions it is added to the list. |
pageSizeOptions | number[] | [10, 20, 50, 100] | The choices offered in the rows-per-page dropdown. |
onPageSizeChange | (pageSize: number) => void | undefined | Fired when the user picks a new rows-per-page value. Recompute
totalPages and usually reset currentPage to 1. |
color | string | undefined | Themes the active page, focus rings, hover states, and dropdown selection highlights — supports preset names (e.g. "indigo", "rose", "emerald", "lavender") or a custom hex string. |