v6.0.35

use-pagination

Manage pagination state
Import

Usage

use-pagination hook is a state management hook for Pagination component, it lets you manage pagination with controlled and uncontrolled state:

const pagination = usePagination({ total: 10, initialPage: 1 });
pagination.range; // -> [1, 2, 3, 4, 5, 'dots', 10];
pagination.setPage(5);
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];
pagination.next();
pagination.range; // -> [1, 'dots', 5, 6, 7, 'dots', 10];
pagination.previous();
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];
pagination.last();
pagination.range; // -> [1, 'dots', 6, 7, 8, 9, 10];
pagination.first();
pagination.range; // -> [1, 2, 3, 4, 5, 'dots', 10];

Controlled

Hook supports controlled mode, provide page and onChange props to manage state from outside:

const [page, onChange] = useState(1);
const pagination = usePagination({ total: 10, page, onChange });
// Will call onChange with 5
pagination.setPage(5);
pagination.range; // -> [1, 'dots', 4, 5, 6, 'dots', 10];
// ... All other examples work the same

Siblings

Control amount of active item siblings with siblings:

const pagination = usePagination({ total: 20, siblings: 3 });
1 sibling (default)
2 siblings
3 siblings

Boundaries

Control amount of items on each boundary with boundaries:

const pagination = usePagination({ total: 20, boundaries: 3 });
1 boundary (default)
2 boundaries
3 boundaries

Definition

function usePagination(settings: {
/** Page selected on initial render, defaults to 1 */
initialPage?: number;
/** Controlled active page number */
page?: number;
/** Total amount of pages */
total: number;
/** Siblings amount on left/right side of selected page, defaults to 1 */
siblings?: number;
/** Amount of elements visible on left/right edges, defaults to 1 */
boundaries?: number;
/** Callback fired after change of each page */
onChange?: (page: number) => void;
}): {
range: (number | 'dots')[];
active: number;
setPage: (page: number) => void;
next: () => void;
previous: () => void;
first: () => void;
last: () => void;
};