Pagination

Full and compact

import { useState } from 'react';
import { Pagination } from '@rookcom/monarch-react';

function PaginationDemo({ compact = false }: { compact?: boolean }) {
  const [page, setPage] = useState(5);
  return compact ? (
    <Pagination
      variant="compact"
      label="Compact pagination"
      page={page}
      pageCount={8}
      pageSize={20}
      totalItems={143}
      onPageChange={setPage}
    />
  ) : (
    <Pagination page={page} pageCount={20} onPageChange={setPage} />
  );
}

<PaginationDemo />
<PaginationDemo compact />

Usage examples

The example at the top of the page is the only one for this component.

Purpose

Moves through a list that is split into pages.

Use when

A table or list is paged on the server or client and the user jumps between pages.

Avoid when

The list grows as the user scrolls or asks for more: use a load-more control.

Design principles

Controlled: the app owns page and fetches data in onPageChange.
The full variant always shows the first and last page and a window around the current one (pageWindow).

API reference

import { Pagination, pageWindow } from '@rookcom/monarch-react';

Export	Kind	Rendering	Root class
`Pagination`	component	client	`.mn-pagination`
`pageWindow`	utility	client	–

pageWindow(page, pageCount, radius = 1) is exported for apps that render their own page list; it returns page numbers and "gap" markers.

Pagination is a function component; it does not forward a ref.

Generated from the TypeScript declarations of packages/react/src/components/navigation/pagination.

Properties

`Pagination`

Prop	Type	Description
`onPageChange` required	`(page: number) => void`
`page` required	`number`	1-based current page.
`pageCount` required	`number`
`className`	`string`
`label`	`string`	Accessible name of the nav.
`pageSize`	`number`	Needed for the compact range text.
`totalItems`	`number`
`variant`	`"compact" \| "full"`	`full` shows numbered pages; `compact` shows "1–20 of 143" with arrows.

Variants

Prop	Values	Description
`variant`	`'full''compact'`	`full` (default) shows numbered pages between previous/next buttons; `compact` shows "1–20 of 143" (or "Page 1 of 8" without `pageSize` and `totalItems`) with the arrows.

States

State	Exposed as	Behaviour
Current page	`aria-current="page"`	Highlighted page button.
First / last page	–	Previous or next button is disabled.
Gap	–	Skipped ranges render as an `aria-hidden` "…".

Interaction behaviour

Previous, next and page buttons call onPageChange with the target page.
Seven or fewer pages are all shown; more pages collapse into gaps.

Keyboard support

Keys	Action
`Tab`	Moves through the previous, page and next buttons.
`Enter / Space`	Goes to that page.

Accessibility

Role: navigation
Accessible name: label prop, default "Pagination".

Page buttons are named "Page N"; arrows "Previous page" and "Next page".
The compact range text is a polite live region, so page changes are announced.

Responsive behaviour

This section is incomplete

No width-specific rules; use the compact variant on narrow layouts. Wrapping of the full variant is not specified.

Theme support

Colours are Monarch semantic tokens only, so light, dark and more-contrast themes apply automatically.

Do and don't

Do

Pass pageSize and totalItems to the compact variant so it shows the item range.
Give each Pagination on one page a distinct label, so the navigation landmarks can be told apart.

Don't

Do not mix pagination and infinite scroll on the same list.

LoadMore: Appends the next page instead of replacing it.
DataTable: The list Pagination usually controls.

Dependencies

Kind	Depends on
npm packages	None
Monarch components	Button

Testing coverage

pageWindow returns a stable window with gaps.
Is a labelled navigation; the current page has aria-current; arrows and page buttons call onPageChange.
Compact variant shows the item range and disables previous on the first page.
No axe violations in jsdom.
Renders on the server.

Check	Covered
Axe in jsdom	Yes
Server rendering	Yes
Browser suites	None yet

Tests: packages/react/src/components/navigation/pagination