GitHub

Pagination

Compact page navigation control with clamped prev and next actions plus ellipsis-based range collapsing for longer result sets.

AccessibleDark Mode

Install

$npx react-principles add pagination

Current page: 5

02

Code Snippet

src/ui/Pagination.tsx
import { Pagination } from "@/ui/Pagination";

<Pagination
  page={page}
  totalPages={12}
  onPageChange={setPage}
  siblingCount={1}
/>
03

Copy-Paste (Single File)

Pagination.tsx
import { cn } from "@/lib/utils";

type PaginationToken = number | "ellipsis";

export interface PaginationProps {
  page: number;
  totalPages: number;
  onPageChange: (page: number) => void;
  siblingCount?: number;
  className?: string;
}

function buildRange(page: number, totalPages: number, siblingCount: number): PaginationToken[] {
  const pages: PaginationToken[] = [];
  const totalButtons = siblingCount * 2 + 5;

  if (totalPages <= totalButtons) {
    for (let i = 1; i <= totalPages; i += 1) pages.push(i);
    return pages;
  }

  const leftSibling = Math.max(page - siblingCount, 1);
  const rightSibling = Math.min(page + siblingCount, totalPages);
  const showLeftEllipsis = leftSibling > 2;
  const showRightEllipsis = rightSibling < totalPages - 1;

  pages.push(1);

  if (showLeftEllipsis) {
    pages.push("ellipsis");
  } else {
    for (let i = 2; i < leftSibling; i += 1) pages.push(i);
  }

  for (let i = leftSibling; i <= rightSibling; i += 1) {
    if (i !== 1 && i !== totalPages) pages.push(i);
  }

  if (showRightEllipsis) {
    pages.push("ellipsis");
  } else {
    for (let i = rightSibling + 1; i < totalPages; i += 1) pages.push(i);
  }

  if (totalPages > 1) pages.push(totalPages);

  return pages;
}
04

Props

PropTypeDefaultDescription
pagenumberCurrent active page number.
totalPagesnumberTotal number of pages available in the range.
onPageChange(page: number) => voidCalled when users move to the previous, next, or a numbered page.
siblingCountnumber1Controls how many pages remain visible on either side of the current page.
classNamestringAdditional classes applied to the pagination nav wrapper.
react-principles