# Pagination

A cross-platform React pagination component that adapts page-button display with ellipses for large page counts.
<!-- BEGIN:xui-mcp-instructions:pagination -->
Pagination splits a large set of results into pages and lets users move between them. It shows the current page, nearby pages, and previous/next arrows, collapsing long ranges with an ellipsis.

### When to use

- To break a long list, table, or set of results into navigable pages
- When the total number of pages is known and users may jump to a specific one

### When not to use

- For continuously loading content — use infinite scroll or a *"Load more"* instead
- For step-by-step flows — use Progress step or a Stepper instead
- When all results comfortably fit on one page

### Content guidelines

Always make the current page clearly distinct from the rest.

Collapse long ranges with *"…"*, keeping the first, last, current, and neighbouring pages visible.

Use page numbers as the main affordance and the arrows for moving one page at a time.

### Behaviour guidelines

Basic shows a small fixed range of pages with arrows.

Advanced-first / -between / -last adapt which numbers and ellipses appear based on whether the current page is near the start, middle, or end.

Previous/next move one page and are disabled at the first and last page.

Selecting a number jumps to that page; the current page is active and not clickable. Size M and S scale the whole control.

### Accessibility

Expose pagination as a navigation landmark with an accessible name (e.g. *"Pagination"*).

Mark the current page with aria-current=*"page"*.

Label the previous/next arrows and disable them at the boundaries; treat the ellipsis as decorative, not a focus stop.

Keep it keyboard-operable with a visible focus indicator.
<!-- END:xui-mcp-instructions:pagination -->

## Installation

```bash
npm install @xsolla/xui-pagination
```

## Imports

```tsx
import { Pagination, type PaginationProps, type PaginationSize } from '@xsolla/xui-pagination';
```

## Quick start

```tsx
import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function QuickStart() {
  const [page, setPage] = React.useState(1);
  return <Pagination currentPage={page} totalPages={10} onPageChange={setPage} />;
}
```

## API Reference

### `<Pagination>`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentPage` | `number` | `1` | Current active page (1-indexed). |
| `totalPages` | `number` | `1` | Total number of pages. |
| `onPageChange` | `(page: number) => void` | — | Callback fired when a page is clicked. |
| `siblingCount` | `number` | `1` | Sibling buttons rendered on each side of the current page. |
| `showNavigation` | `boolean` | `true` | Show previous/next chevron buttons. |
| `stretched` | `boolean` | `false` | Stretch the container to full width and centre items. |
| `disabled` | `boolean` | `false` | Disable all interactions. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Item size and typography. |
| `backgroundColor` | `string` | — | Custom background colour for the container. |
| `testID` | `string` | — | Test identifier. |

*Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).*

### Page-number display

With `siblingCount=1` and `totalPages=20`:

- Page 1 → `1 2 3 4 5 … 20`
- Page 10 → `1 … 9 10 11 … 20`
- Page 20 → `1 … 16 17 18 19 20`

## Examples

### Sizes

```tsx
import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function PaginationSizes() {
  const [page, setPage] = React.useState(3);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Pagination size="sm" currentPage={page} totalPages={10} onPageChange={setPage} />
      <Pagination size="md" currentPage={page} totalPages={10} onPageChange={setPage} />
      <Pagination size="lg" currentPage={page} totalPages={10} onPageChange={setPage} />
    </div>
  );
}
```

### Without navigation

```tsx
import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function NoNavigation() {
  const [page, setPage] = React.useState(1);
  return (
    <Pagination
      currentPage={page}
      totalPages={8}
      onPageChange={setPage}
      showNavigation={false}
    />
  );
}
```

### More sibling pages

```tsx
import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function MoreSiblings() {
  const [page, setPage] = React.useState(10);
  return (
    <Pagination
      currentPage={page}
      totalPages={50}
      onPageChange={setPage}
      siblingCount={2}
    />
  );
}
```

### Disabled

```tsx
import * as React from 'react';
import { Pagination } from '@xsolla/xui-pagination';

export default function DisabledPagination() {
  return <Pagination currentPage={5} totalPages={10} disabled />;
}
```

## Accessibility

- Page buttons have `aria-label="Go to page N"` and the active page sets `aria-current="page"`.
- Previous/next buttons use `aria-label="Previous page"` and `aria-label="Next page"`.
- All clickable items have `role="button"`; disabled or boundary states show a `not-allowed` cursor and reduced opacity.