# Pagination

## Overview

The pagination component presents table paging controls and summary text in a compact navigation row.

The component styles pagination-specific content inside a native `<nav class="pagination">`, with optional summary text in a `<p>` and page controls as links.

Pagination is still a navigation pattern, but it serves a narrower purpose than primary navigation: it moves through slices of a result set rather than between peer destinations in the product.

## When to use

Use pagination to move through slices of tabular results while keeping the controls grouped with the current result range.

## When not to use

Do not use pagination for peer destinations, workflow steps, or non-tabular navigation; use nav or stepper.

## Usage

```html
<nav class="pagination" aria-label="Pagination for search results">
  <p>1-10 of 42</p>
  <a href="?page=1" aria-label="Previous page">Previous</a>
  <a href="?page=3" aria-label="Next page">Next</a>
</nav>
```

Use this component when the interface needs to page through table results and keep the paging affordances grouped with the current range.

Use a different navigation pattern instead when the controls do not paginate tabular data.

Use a specific navigation label that identifies the paged result set.

Use real links for page changes so pagination remains navigable without JavaScript.

Visual grouping is acceptable, but the controls should continue to behave like links instead of action buttons.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js).

- PAG-001: Row alignment and wrapping are built into the pagination component, and controls align to the inline end by default.
- PAG-002: Summary text remains unwrapped so ranges stay easy to scan.
- PAG-003: Pagination links inherit the shared control height and horizontal rhythm without taking on button semantics.
- PAG-004: Pagination icons use `--pagination-icon-color`, which defaults to a theme text token and can be overridden by the component consumer.
- PAG-005: Comfortable and compact density should come from the shared layout tokens rather than pagination-specific theme branches.
## Accessibility

- Use a native `<nav>` so assistive technologies can announce the region as navigation.
- Keep `class="pagination"` on the navigation element so the component styles activate.
- Use a specific `aria-label` on the navigation element so assistive technologies can distinguish pagination regions when a page has more than one result set.
- Use descriptive link text or `aria-label` values so previous and next controls are clear out of context.
- Keep the summary text in the DOM so the current item range is available to all users.
- Do not replace links with non-semantic elements for page navigation.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--pagination-color-text` | `<color>` | Sets --pagination-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-min-height` | `<length>` | Sets --pagination-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-padding-block` | `<length>` | Sets --pagination-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-control-padding-inline` | `<length>` | Sets --pagination-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--pagination-icon-color` | `<color>` | Sets the color of pagination icons; change it when previous and next controls need to match a different navigation context. |
| `--pagination-space-inline` | `<length>` | Sets --pagination-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-text`
- `--layout-control-min-height`
- `--layout-control-padding-block`
- `--layout-control-padding-inline`
- `--layout-space-inline`