Async & APIIntermediateSSR-safehooks/async/usePagination.ts

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 · usePagination
Editor
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.ts for implementation details