Pagination

Pagination moves a user through a long list of pages. It computes the visible page window — with ellipsis gaps when there are too many — and hands each control back through a render prop.

What it is

A single component that owns the page-window arithmetic. Given the current page, the total, and the siblings count, it works out which page numbers to show, where the ellipsis gaps fall, and whether the previous and next controls are disabled. It does not render the buttons — your renderItem does, once per control, from the descriptor Pagination passes it.

Pagination is controlled-only: it holds no internal page state. You own page and update it from the onPageChange callback.

Install

yarn add @usemotif/headless

import { Pagination } from '@usemotif/headless';

API

function Pagination(props: PaginationProps): JSX.Element

Accessibility

Pagination renders a nav landmark named by aria-label. Each control comes from your renderItem, so the accessible markup is yours to get right: the current page should carry aria-current="page" (use the selected flag), and the previous and next controls need discernible names — "Previous page", "Next page" — not just a chevron glyph. The disabled flag tells you when to disable a control rather than hide it.

Examples

A standard pagination bar:

<Pagination
page={page}
total={pageCount}
onPageChange={setPage}
renderItem={({ type, page: p, selected, disabled, onClick }) => {
  if (type === 'ellipsis') return <Text>…</Text>;
  if (type === 'previous') {
    return (
      <Button aria-label="Previous page" disabled={disabled} onPress={onClick}>
        ‹
      </Button>
    );
  }
  if (type === 'next') {
    return (
      <Button aria-label="Next page" disabled={disabled} onPress={onClick}>
        ›
      </Button>
    );
  }
  return (
    <Button
      aria-current={selected ? 'page' : undefined}
      intent={selected ? 'primary' : 'neutral'}
      onPress={onClick}
    >
      {p}
    </Button>
  );
}}
/>