Usage
Builds pagination state and helpers for controlled or uncontrolled page navigation. Generates a range array with page numbers and ellipsis dots, and provides navigation functions.
import { usePagination } from '@kuzenbo/hooks';
function Demo() {
const pagination = usePagination({ total: 10 });
return (
<div>
<div>
{pagination.range.map((page, index) => (
<button
key={index}
onClick={() => typeof page === 'number' && pagination.setPage(page)}
disabled={page === 'dots' || page === pagination.active}
>
{page === 'dots' ? '...' : page}
</button>
))}
</div>
<p>Active page: {pagination.active}</p>
</div>
);
}
With navigation controls
Use the provided navigation helpers:
import { usePagination } from '@kuzenbo/hooks';
function Demo() {
const { range, active, setPage, next, previous, first, last } = usePagination({
total: 20,
siblings: 1,
boundaries: 1,
});
return (
<div>
<button onClick={first}>First</button>
<button onClick={previous}>Previous</button>
{range.map((page, index) => (
<button
key={index}
onClick={() => typeof page === 'number' && setPage(page)}
disabled={page === 'dots' || page === active}
>
{page === 'dots' ? '...' : page}
</button>
))}
<button onClick={next}>Next</button>
<button onClick={last}>Last</button>
</div>
);
}
Control the active page externally:
import { usePagination } from '@kuzenbo/hooks';
import { useState } from 'react';
function Demo() {
const [page, setPage] = useState(1);
const pagination = usePagination({
total: 15,
page,
onChange: setPage,
});
return (
<div>
<p>Current page: {page}</p>
{pagination.range.map((item, index) => (
<button
key={index}
onClick={() => typeof item === 'number' && setPage(item)}
disabled={item === 'dots' || item === page}
>
{item === 'dots' ? '...' : item}
</button>
))}
</div>
);
}
Custom start value
Start pagination from a custom number:
import { usePagination } from '@kuzenbo/hooks';
function Demo() {
const pagination = usePagination({
total: 10,
startValue: 0, // Pages: 0, 1, 2, ..., 9
});
return (
<div>
{pagination.range.map((page, index) => (
<button
key={index}
onClick={() => typeof page === 'number' && pagination.setPage(page)}
>
{page === 'dots' ? '...' : page}
</button>
))}
</div>
);
}
Definition
interface UsePaginationOptions {
initialPage?: number;
page?: number;
total: number;
siblings?: number;
boundaries?: number;
onChange?: (page: number) => void;
startValue?: number;
}
interface UsePaginationReturnValue {
range: (number | 'dots')[];
active: number;
setPage: (page: number) => void;
next: () => void;
previous: () => void;
first: () => void;
last: () => void;
}
function usePagination(
options: UsePaginationOptions
): UsePaginationReturnValue
Parameters
Initial active page for uncontrolled usage
First page number, defaults to 1
Number of sibling pages shown around the active page
Number of page items always shown at each edge
Called whenever the active page changes
Returns
Array of page numbers and dots for rendering pagination
Current active page number
Function to set active page
Function to go to next page
Function to go to previous page
Function to go to first page
Function to go to last page