A React hook to help manage pagination state

✨ Features

• 🛠 State-only hook & callbacks, you provide your own UI controls
• 📦 Compatible with any pagination method like GraphQL Relay Cursor, OData, etc.
• ⚡️ Works with both server side and client side pagination
• 🐜 Simple and lightweight — less than 2KB gzipped

Example

1import { usePagination } from "react-use-pagination";
2
3function App() {
4    const [data] = React.useState([]); // <- your data
5
6    const {
7        currentPage,
8        totalPages,
9        setNextPage,
10        setPreviousPage,
11        nextEnabled,
12        previousEnabled,
13        startIndex,
14        endIndex,
15    } = usePagination({ totalItems: data.length });
16
17    return (
18        <div>
19            <MyDataTable data={data.slice(startIndex, endIndex)} />
20
21            <button onClick={setPreviousPage} disabled={!previousEnabled}>
22                Previous Page
23            </button>
24            <span>
25                Current Page: {currentPage} of {totalPages}
26            </span>
27            <button onClick={setNextPage} disabled={!nextEnabled}>
28                Next Page
29            </button>
30        </div>
31    );
32}

API

const paginationState = usePagination(options);

options

1type Options = {
2    totalItems: number;
3    initialPage?: number; // (default: 0)
4    initialPageSize?: number; // (default: 0)
5};

paginationState

1type PaginationState = {
2    // The current page
3    currentPage: number;
4
5    // The first index of the page window
6    startIndex: number;
7
8    // The last index of the page window
9    endIndex: number;
10
11    // Whether the next button should be enabled
12    nextEnabled: number;
13
14    // Whether the previous button should be enabled
15    previousEnabled: number;
16
17    // The total page size
18    pageSize: number;
19
20    // Jump directly to a page
21    setPage: (page: number) => void;
22
23    // Jump to the next page
24    setNextPage: () => void;
25
26    // Jump to the previous page
27    setPreviousPage: () => void;
28
29    // Set the page size
30    setPageSize: (pageSize: number, nextPage?: number = 0) => void;
31};

Client Side Pagination

startIndex and endIndex can be used to implement client-side pagination. The simplest possible usage is to pass these properties directly to Array.slice:

1const [data] = React.useState(["apple", "banana", "cherry"]);
2const { startIndex, endIndex } = usePagination({ totalItems: data.length, initialPageSize: 1 });
3
4return (
5    <ul>
6        {data.slice(startIndex, endIndex).map((item) => (
7            <li>{item}</li>
8        ))}
9    </ul>
10);

Server Side Pagination

startIndex and pageSize can be used to implement a standard limit/offset (also known as top/skip) type of pagination:

1// Keep track of length separately from data, since data fetcher depends on pagination state
2const [length, setLength] = React.useState(0);
3
4// Pagination hook
5const { startIndex, pageSize } = usePagination({ totalItems: length, initialPageSize: 1 });
6
7// Fetch Data
8const [_, data] = usePromise(
9    React.useCallback(
10        () => fetchUsers({ offset: startIndex, limit: pageSize }),
11        [startIndex, pageSize]
12    )
13);
14
15// When data changes, update length
16React.useEffect(() => {
17    setLength(data.length);
18}, [data]);
19
20return (
21    <ul>
22        {data.slice(startIndex, endIndex).map((item) => (
23            <li>{item}</li>
24        ))}
25    </ul>
26);