usePagination
Page / pageSize / total helpers.
Import
TypeScript
import { usePagination } from '@/hooks';API
Signature
usePagination(options?) → pagination state
When to use
Tables and lists with server or client paging.
SSR / Next.js
Client-side. Prefer RSC for first-paint server data.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · usePaginationEditor
function TablePager({ total }: { total: number }) { const p = usePagination({ initialPage: 1, initialPageSize: 10, total }); return ( <div> <p> Page {p.page}/{p.totalPages} · offset {p.offset} </p> <button disabled={!p.canPrev} onClick={p.prev}>Prev</button> <button disabled={!p.canNext} onClick={p.next}>Next</button> </div> ); }
Preview
Implementation source
Full library source for usePagination — copy into your project when you are not installing a package yet.
hooks/async/usePagination.ts
import { useCallback, useMemo, useState } from 'react';
import type { PaginationState } from '../types';
export interface UsePaginationOptions {
initialPage?: number;
initialPageSize?: number;
total?: number;
}
export interface UsePaginationReturn extends PaginationState {
setPage: (page: number) => void;
setPageSize: (size: number) => void;
setTotal: (total: number) => void;
next: () => void;
prev: () => void;
canNext: boolean;
canPrev: boolean;
offset: number;
}
/** Client-side pagination state helper. */
export function usePagination(
options: UsePaginationOptions = {},
): UsePaginationReturn {
const {
initialPage = 1,
initialPageSize = 10,
total: initialTotal = 0,
} = options;
const [page, setPageRaw] = useState(initialPage);
const [pageSize, setPageSize] = useState(initialPageSize);
const [total, setTotal] = useState(initialTotal);
const totalPages = Math.max(1, Math.ceil(total / pageSize) || 1);
const setPage = useCallback(
(next: number) => {
setPageRaw(Math.min(Math.max(1, next), totalPages));
},
[totalPages],
);
const next = useCallback(() => setPage(page + 1), [page, setPage]);
const prev = useCallback(() => setPage(page - 1), [page, setPage]);
return useMemo(
() => ({
page,
pageSize,
total,
totalPages,
setPage,
setPageSize: (size: number) => {
setPageSize(size);
setPageRaw(1);
},
setTotal,
next,
prev,
canNext: page < totalPages,
canPrev: page > 1,
offset: (page - 1) * pageSize,
}),
[page, pageSize, total, totalPages, setPage, next, prev],
);
}
Copy-paste example
usePagination.example.tsx
'use client';
import { usePagination } from '@/hooks';
export function TablePager({ total }: { total: number }) {
const p = usePagination({ initialPage: 1, initialPageSize: 10, total });
return (
<div>
<p>
Page {p.page}/{p.totalPages} · offset {p.offset}
</p>
<button disabled={!p.canPrev} onClick={p.prev}>Prev</button>
<button disabled={!p.canNext} onClick={p.next}>Next</button>
</div>
);
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Abort in-flight work when the URL changes. Prefer null URL / enabled:false to skip.
- Source of truth: open
hooks/async/usePagination.tsfor implementation details