Pagination

since v8.5.0

Page navigation for paged collections. Owns the current-page state

(controlled via page/onPageChange or uncontrolled via defaultPage) and

renders one of three layouts via variant.

Built natively — no behavior dependency. Renders a <nav aria-label>

landmark; the active page carries aria-current="page"; the arrows disable

at the boundaries. All targets are ≥36px (DESIGN.md AA target size).

Install

Add the package and import the component.

pnpm add @hey-mike/tungsten

pnpm add @hey-mike/tungsten

import { Pagination } from '@hey-mike/tungsten';

import { Pagination } from '@hey-mike/tungsten';

Preview

Same fixtures used by the visual-regression suite.

Open snapshot in new view →

Usage

apps/docs/app/snapshots/pagination/page.tsx

'use client';

import { Pagination } from '@hey-mike/tungsten';
import { VariantGrid } from '../_components/VariantGrid';

export default function PaginationSnapshot() {
  return (
    <VariantGrid
      title="Pagination"
      variants={[
        {
          label: 'default (start)',
          node: <Pagination totalPages={10} defaultPage={1} />,
        },
        {
          label: 'default (middle, both ellipses)',
          node: <Pagination totalPages={20} defaultPage={10} />,
        },
        {
          label: 'compact',
          node: <Pagination variant="compact" totalPages={8} defaultPage={3} />,
        },
        {
          label: 'jump-to',
          node: <Pagination variant="jump-to" totalPages={12} defaultPage={5} />,
        },
      ]}
    />
  );
}

'use client';

import { Pagination } from '@hey-mike/tungsten';
import { VariantGrid } from '../_components/VariantGrid';

export default function PaginationSnapshot() {
  return (
    <VariantGrid
      title="Pagination"
      variants={[
        {
          label: 'default (start)',
          node: <Pagination totalPages={10} defaultPage={1} />,
        },
        {
          label: 'default (middle, both ellipses)',
          node: <Pagination totalPages={20} defaultPage={10} />,
        },
        {
          label: 'compact',
          node: <Pagination variant="compact" totalPages={8} defaultPage={3} />,
        },
        {
          label: 'jump-to',
          node: <Pagination variant="jump-to" totalPages={12} defaultPage={5} />,
        },
      ]}
    />
  );
}

Props

Surface specific to <Pagination />.

Prop	Type	Default	Description
totalPages*	`number`	—	Total number of pages. Page indices are 1-based.
page	`number`	—	Controlled current page. Provide alongside `onPageChange`.
defaultPage	`number`	`1`	Initial page in uncontrolled mode. Ignored when `page` is provided. Defaults to 1.
onPageChange	`((page: number) => void)`	—	Fires with the next page (already clamped to `[1, totalPages]`).
variant	`"default" \| "compact" \| "jump-to"`	`default`	Layout: - `default` — full windowed page list with first/last + ellipsis - `compact` — "Page X of N" status between the arrows - `jump-to` — a page-number input between the arrows
siblingCount	`number`	`1`	Pages shown either side of the current page in the `default` variant. Defaults to 1.

Used in recipes