usePaginationui-interaction
usePagination
NewSSR SAFEControls dataset pagination metrics, slice bounds, and UI navigation range with ellipsis handling.
$ pnpm dlx shadcn@latest add @byphongphan/use-paginationRequires
@byphongphan in components.jsonuse-pagination.tsx
Loading preview...
Installation
$ pnpm dlx shadcn@latest add @byphongphan/use-paginationRequires
@byphongphan in components.jsonUsage
In-Memory Client-Side List
Server-Side Data Fetching
Features
- Ellipsis Generation: Computes compact numeric navigation ranges with
"..."tokens based on customizablesiblingsandboundaries. - Built-in Slicing (
slice): Provides a memory-efficientslice(array)helper that calculates zero-based index boundaries automatically. - Display Indices Ready: Returns
itemStartanditemEnd(1-based human display numbers) to easily render "Showing 11 to 20 of 100". - Dynamic Auto-Clamping: Automatically clamps the active page to
totalPageswhenevertotalItemsdecreases (e.g. after searching or applying filters). - Navigation Shortcuts: Built-in
first(),last(),prev(), andnext()helpers alongside directsetPage(n).
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
options.totalItems | number | — | Total count of items in the entire dataset. |
options.initialPage | number | 1 | Initial page number (1-based). |
options.initialPageSize | number | 10 | Initial number of items per page. |
options.siblings | number | 1 | Number of visible page buttons on each side of the active page. |
options.boundaries | number | 1 | Number of visible page buttons at the extreme start and end. |
options.onChange | (page: number, pageSize: number) => void | — | Optional callback fired whenever the active page or page size is modified. |
Returns
Returns a UsePaginationReturn<T> object:
| Property | Type | Description |
|---|---|---|
page | number | Current active page (1-based index). |
pageSize | number | Current number of items rendered per page. |
totalPages | number | Total calculated pages based on totalItems and pageSize. |
range | (number | "...")[] | Computed list of page numbers and ellipsis tokens for UI button rendering. |
startIndex | number | Zero-based start index, ideal for items.slice(startIndex, endIndex). |
endIndex | number | Zero-based exclusive end index for array slicing. |
itemStart | number | One-based display index of the first item on current page (e.g. "Showing 11"). |
itemEnd | number | One-based display index of the last item on current page. |
isFirstPage | boolean | Whether currently on page 1. |
isLastPage | boolean | Whether currently on the last page. |
hasPrevPage | boolean | Whether backward navigation is possible (page > 1). |
hasNextPage | boolean | Whether forward navigation is possible (page < totalPages). |
setPage | (page: number) => void | Navigates directly to a target page with clamping. |
setPageSize | (pageSize: number, resetToFirstPage?: boolean) => void | Updates page size with optional reset to page 1. |
next | () => void | Moves forward by 1 page. |
prev | () => void | Moves backward by 1 page. |
first | () => void | Jumps directly to page 1. |
last | () => void | Jumps directly to the final page. |
slice | (data: readonly T[]) => T[] | Slices an arbitrary in-memory array for current page items. |