Skip to main content

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>
  );
}

Controlled pagination

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

options
UsePaginationOptions
total
number
required
Total number of pages
page
number
Controlled active page
initialPage
number
Initial active page for uncontrolled usage
startValue
number
default:1
First page number, defaults to 1
siblings
number
default:1
Number of sibling pages shown around the active page
boundaries
number
default:1
Number of page items always shown at each edge
onChange
(page: number) => void
Called whenever the active page changes

Returns

range
(number | 'dots')[]
Array of page numbers and dots for rendering pagination
active
number
Current active page number
setPage
(page: number) => void
Function to set active page
next
() => void
Function to go to next page
previous
() => void
Function to go to previous page
first
() => void
Function to go to first page
last
() => void
Function to go to last page

Build docs developers (and LLMs) love