Pagination

Overview

Pagination uses the “page of total” counter pattern, not numbered page links. Five controls — First / Previous / a static “X of Y” indicator / Next / Last — fit any number of pages without changing width. Reach for it on table footers, dialog lists, archive views — anywhere a row of data spans more rows than the viewport can hold.

Variants

Two display modes. compact (default) is icon-only — built for table footers where horizontal space is tight. labeled adds the word next to each chevron — used in dialogs and any surface where the buttons should announce their target action without relying on icon literacy.

States

Bounded — at the first page, First and Previous disable themselves; at the last page, Next and Last disable. The component clamps the page prop so an out-of-range value still renders correctly.

Try it

Click or tab to the buttons and press Enter / Space to navigate. The indicator is wrapped in an aria-live="polite" region so assistive tech announces the new page on every change.

In a table

The most common surface. Pair the pagination with a row-count summary on the opposite edge so the footer reads as a single balanced strip.

Localised

Pass a labelsprop to swap each control's text and override the “X of Y” format. Required for any market where en-GB strings aren't the right answer.

Anatomy

Five named parts. The indicator is the only static element — the four buttons sit on either side, equally spaced.

Behavior

• 01Hidden when there's only one page. totalPages ≤ 1 renders nothing — never a disabled-everywhere stub. If the data fits on one page, no pagination chrome is the right answer.
• 02Page is clamped on render. An out-of-range pageprop (e.g. page 99 of 4) is clamped to the valid range, so the component never gets stuck in an unreachable state if the parent's data shrinks.
• 03No keyboard shortcuts beyond Tab. Power users get arrow keys when they tab into a button — that's native browser behaviour. The component doesn't hijack global ←/→ because that conflicts with text fields, tables, and other surfaces.
• 04First / Last are opt-out, not opt-in. They ship by default because jumping to the end of long lists is the second-most-common pagination action. Pass showFirstLast={false} when the surface only has room for the three middle controls.

Accessibility

• Nav landmark. The component renders as a <nav> with aria-label="Pagination" (override via ariaLabel) so screen readers can jump to it as a region.
• Icon-only buttons announce their action. The compact variant sets aria-labelon each button (“First”, “Previous”, …) so the chevron isn't the only signal.
• Live indicator.The “X of Y” counter sits in an aria-live="polite" + aria-atomic="true" region — every page change is announced as one statement, not character-by-character.
• Disabled state at bounds. First / Previous use the native disabled attribute when at page 1; Next / Last when at the final page. Disabled buttons are removed from the tab order — the user doesn't land on a dead control.
• Tabular numerals. The indicator uses tabular-nums + slashed-zeroso digits don't shift width as the page count climbs from 9 to 10 to 100.

Code

Import from @flatpay-dk/ui. Pagination is a controlled component — you own the page state and pass it back via onPageChange.

import { Pagination } from "@flatpay-dk/ui";

// Default — compact, with First / Last
const [page, setPage] = useState(1);

<Pagination
  page={page}
  totalPages={Math.ceil(rows.length / pageSize)}
  onPageChange={setPage}
/>

// Labeled — chevron + text
<Pagination
  page={page}
  totalPages={4}
  variant="labeled"
  onPageChange={setPage}
/>

// Without First / Last
<Pagination
  page={page}
  totalPages={totalPages}
  showFirstLast={false}
  onPageChange={setPage}
/>

// Localised — pass labels
<Pagination
  page={page}
  totalPages={totalPages}
  onPageChange={setPage}
  labels={{
    first: "Første",
    previous: "Forrige",
    next: "Næste",
    last: "Sidste",
    indicator: (p, t) => `${p} af ${t}`,
  }}
/>

// In a table footer with row-count
<div className="flex items-center justify-between">
  <p className="font-mono text-[12px] text-muted-foreground">
    {(page - 1) * 25 + 1}–{Math.min(page * 25, total)} of {total}
  </p>
  <Pagination
    page={page}
    totalPages={Math.ceil(total / 25)}
    onPageChange={setPage}
  />
</div>

Best practices

Props

Related