# Pagination

> Accessible page navigation for long lists and tables, with previous, next and compact modes.

Category: Navigation · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/pagination

Use Pagination below tables and lists that are split into pages. The visible page numbers keep a stable width as the page changes, so the control never jumps under the pointer. Use the compact variant in tight spaces, and getHref when each page has its own URL.

## Import

```tsx
import { Pagination } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { useState } from 'react';
import { Pagination } from '@bindshq/stance-react';

export function Basic() {
  const [page, setPage] = useState(4);
  return <Pagination page={page} pageCount={24} onPageChange={setPage} />;
}
```

### Compact

“Page x of y” with previous and next buttons; the summary is announced politely when it changes.

```tsx
import { useState } from 'react';
import { Pagination } from '@bindshq/stance-react';

export function Compact() {
  const [page, setPage] = useState(3);
  return <Pagination variant="compact" page={page} pageCount={12} onPageChange={setPage} />;
}
```

### As links

getHref renders anchors, so pages can be opened in new tabs and crawled.

```tsx
import { Pagination } from '@bindshq/stance-react';

export function Links() {
  return <Pagination page={2} pageCount={8} getHref={(p) => `#page-${p}`} />;
}
```

### Sibling and boundary counts

```tsx
import { useState } from 'react';
import { Pagination } from '@bindshq/stance-react';

export function MoreSiblings() {
  const [page, setPage] = useState(10);
  return (
    <Pagination
      page={page}
      pageCount={40}
      siblingCount={2}
      boundaryCount={2}
      onPageChange={setPage}
    />
  );
}
```

### Small with text labels

```tsx
import { useState } from 'react';
import { Pagination } from '@bindshq/stance-react';

export function Small() {
  const [page, setPage] = useState(1);
  return (
    <Pagination size="sm" showPrevNextLabels page={page} pageCount={5} onPageChange={setPage} />
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Pagination | `page` (required) | `number` | None | Current page, 1-based. |
| Pagination | `pageCount` (required) | `number` | None | Total number of pages. |
| Pagination | `onPageChange` | `(page: number) => void` | None | Called with the requested page. |
| Pagination | `siblingCount` | `number` | `1` | Pages shown either side of the current page. |
| Pagination | `boundaryCount` | `number` | `1` | Pages always shown at each end. |
| Pagination | `variant` | `'full' \| 'compact'` | `'full'` | Page numbers or a “Page x of y” summary. |
| Pagination | `size` | `'sm' \| 'md'` | `'md'` | Item height. |
| Pagination | `getHref` | `(page: number) => string` | None | Render items as links. |
| Pagination | `showPrevNextLabels` | `boolean` | `false` | Show “Previous” / “Next” text beside the arrows. |
| Pagination | `labels` | `Partial<PaginationLabels>` | None | Translatable strings: nav, previous, next, page(n), summary(n, count). |
| Pagination | `disabled` | `boolean` | `false` | Disable all items, e.g. while loading. |

## Accessibility

- A <nav> landmark named “Pagination” (configurable) containing a list.
- Every item has a spoken label such as “Page 4”; the current page has aria-current="page".
- Previous and next are disabled at the ends instead of disappearing, so the layout does not shift.
- Ellipses are decorative and hidden from assistive technology.

## Keyboard

| Keys | Action |
| --- | --- |
| `Tab` | Moves between page controls. |
| `Enter` `Space` | Goes to the page. |

## Guidelines

**Do**

- Show the total number of results near the table.
- Move focus to the top of the results after changing page.

**Don’t**

- Use pagination for fewer than two pages.
- Combine with infinite scroll on the same list.

## Related

- https://stanceui.com/components/data-table
- https://stanceui.com/components/table