Source: https://monarchui.dev/components/pagination/

Components · Navigation

# Pagination

Numbered or compact page navigation for long lists.

@rookcom/monarch-react

Component

## Full and 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

```tsx
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.

## Related components

- [LoadMore](https://monarchui.dev/components/load-more/): Appends the next page instead of replacing it.
- [DataTable](https://monarchui.dev/components/data-table/): The list Pagination usually controls.

## Dependencies

| Kind | Depends on |
| --- | --- |
| npm packages | None |
| Monarch components | [Button](https://monarchui.dev/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`

## All example code

### Full and compact

```tsx
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 />
```