Pagination

Controls for moving through a paged collection one page at a time, with automatic ellipses and configurable sibling/boundary counts.

stable
since v0.1.0
2.4 kB
navigation
pagination
accessible

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [page, setPage] = useState(1);
  return <Pagination totalPages={8} currentPage={page} onPageChange={setPage} />;
}

Variants

Sizes

Use size="sm", "md" (default), or "lg" to match surrounding density.

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [page, setPage] = useState(3);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <Pagination totalPages={8} currentPage={page} onPageChange={setPage} size="sm" />
      <Pagination totalPages={8} currentPage={page} onPageChange={setPage} size="md" />
      <Pagination totalPages={8} currentPage={page} onPageChange={setPage} size="lg" />
    </div>
  );
}

First and last buttons

Set showFirstLast to render skip-to-first and skip-to-last buttons alongside Prev / Next.

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [page, setPage] = useState(5);
  return <Pagination totalPages={20} currentPage={page} onPageChange={setPage} showFirstLast />;
}

Sibling and boundary counts

siblingCount (default 1) controls how many pages render either side of the current page; boundaryCount (default 1) controls how many pages stick to each end. Ellipses fill the gaps.

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [page, setPage] = useState(10);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <span style={{ fontSize: '0.875rem', color: 'var(--cynosure-color-fg-muted)' }}>
        siblingCount=2, boundaryCount=2
      </span>
      <Pagination
        totalPages={30}
        currentPage={page}
        onPageChange={setPage}
        siblingCount={2}
        boundaryCount={2}
      />
      <span style={{ fontSize: '0.875rem', color: 'var(--cynosure-color-fg-muted)' }}>
        siblingCount=0, boundaryCount=1
      </span>
      <Pagination
        totalPages={30}
        currentPage={page}
        onPageChange={setPage}
        siblingCount={0}
        boundaryCount={1}
      />
    </div>
  );
}

Disabled

Pass disabled to freeze the whole control (e.g. while loading the next page).

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <Pagination totalPages={8} currentPage={3} onPageChange={() => {}} disabled />;
}

Localised labels

Use the labels prop to translate or rewrite each button’s accessible name.

Preview

Open

tsx

import { Pagination } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [page, setPage] = useState(2);
  return (
    <Pagination
      totalPages={8}
      currentPage={page}
      onPageChange={setPage}
      labels={{
        previous: 'Page précédente',
        next: 'Page suivante',
        page: (p) => `Aller à la page ${p}`,
        current: (p) => `Page ${p}, page actuelle`,
      }}
      aria-label="Pagination des résultats"
    />
  );
}

API

PropTypeDefaultDescription

totalPages*

number

—

Total number of pages (1-indexed). Clamped to >= 1 internally.

currentPage*

number

—

Currently active page (1-indexed).

onPageChange*

(page: number) => void

—

Fired with the new page number when navigation occurs.

size

"sm"|"md"|"lg"

Visual size of the page buttons.

siblingCount

number

Number of siblings to display on either side of the current page before showing an ellipsis.

boundaryCount

number

Number of pages always rendered at the start and end of the range (before the ellipsis on either side).

showFirstLast

boolean

false

Render dedicated "first" / "last" jump buttons in the default layout.

disabled

boolean

false

Disable every control. Useful while a page transition is in flight.

labels

PaginationLabels

—

Localised labels for the navigation buttons.

children

ReactNode

—

Custom children compose their own layout (compound mode). Omit for the prop-driven default: Prev / page list / Next, optionally bracketed by First / Last.

aria-label

string

"Pagination"

Accessible label for the wrapping `<nav>` element.

Accessibility

The root renders a <nav> landmark; pass aria-label (default "Pagination") to name it.
Each page button receives a descriptive aria-label like "Go to page 4"; the current page is announced as "Page 4, current page".
The current button carries aria-current="page" so screen readers identify the active position.
Prev / Next / First / Last buttons become disabled (and unfocusable) at the edges of the range rather than disappearing.
Ellipsis placeholders are aria-hidden="true" so they don’t pollute announcements.

Recipes

Sync currentPage to a ?page= URL search param so deep links survive refresh.
Lower siblingCount to 0 and raise boundaryCount to 2 for a compact “first … current … last” layout.
Pair with a Select for “items per page” controls in dense tables.
Customise labels.page to include the total count, e.g. (p) => `Go to page ${p} of 42`.