# React Native Pagination

> Accessible React Native pagination for iOS, Android and the web: Previous and Next, page numbers with ellipses, or a compact 'Page 3 of 10', controlled or uncontrolled, in a brand, iOS, Material 3 or web design.

# Pagination

Page buttons for a long list, a table or search results: Previous, the pages around the current one with ellipses, and Next. The `compact` variant fits a phone. For an endless feed, load more as the user scrolls instead.

```tsx
import { Pagination } from 'patine-ui';
```

```tsx live
import { Box, List, ListItem, Pagination, Text } from 'patine-ui';

const ORDERS = Array.from({ length: 87 }, (_, i) => ({ id: 1040 + i, total: ((i * 37) % 180) + 20 }));
const PER_PAGE = 4;

export default function Example() {
  const [page, setPage] = React.useState(1);
  const shown = ORDERS.slice((page - 1) * PER_PAGE, page * PER_PAGE);
  return (
    <Box gap="md" style={{ maxWidth: 480 }}>
      <List title="Orders">
        {shown.map((o) => (
          <ListItem key={o.id} title={`Order #${o.id}`} value={`$${o.total}.00`} />
        ))}
      </List>
      <Pagination pageCount={Math.ceil(ORDERS.length / PER_PAGE)} page={page} onPageChange={setPage} iconOnly />
      <Text size="sm" color="textSecondary">Showing {(page - 1) * PER_PAGE + 1}–{Math.min(page * PER_PAGE, ORDERS.length)} of {ORDERS.length}</Text>
    </Box>
  );
}
```

## Example: search results

A help center's search: ten results a page, the page goes back to 1 when the query changes, and the compact variant keeps the controls short on a phone.

```tsx live
import { useState } from 'react';
import { Box, List, ListItem, Pagination, SearchField, Text } from 'patine-ui';

const TOPICS = ['Billing', 'Shipping', 'Returns', 'Your account', 'Security'];
const ARTICLES = Array.from({ length: 64 }, (_, i) => ({
  id: i,
  topic: TOPICS[i % TOPICS.length],
  title: `${['How to', 'Why', 'When to', 'Can I'][i % 4]} ${['change', 'track', 'cancel', 'update', 'download', 'reset', 'share', 'pause'][i % 8]} ${['an order', 'my invoice', 'a return', 'my password', 'a gift card', 'my address'][i % 6]}`,
}));
const PER_PAGE = 10;

export default function Example() {
  const [query, setQuery] = useState('');
  const [page, setPage] = useState(1);
  const hits = ARTICLES.filter((a) => `${a.title} ${a.topic}`.toLowerCase().includes(query.toLowerCase()));
  const pageCount = Math.max(1, Math.ceil(hits.length / PER_PAGE));
  return (
    <Box gap="md" style={{ width: '100%', maxWidth: 480 }}>
      <SearchField
        value={query}
        onChangeText={(text) => {
          setQuery(text);
          setPage(1);
        }}
        placeholder="Search help articles"
      />
      <Text size="sm" color="textSecondary">{hits.length} articles</Text>
      <List>
        {hits.slice((page - 1) * PER_PAGE, page * PER_PAGE).map((a) => (
          <ListItem key={a.id} title={a.title} description={a.topic} onPress={() => {}} />
        ))}
      </List>
      {hits.length > PER_PAGE ? <Pagination variant="compact" pageCount={pageCount} page={page} onPageChange={setPage} /> : null}
    </Box>
  );
}
```

## Which pages show

Both ends, the current page with `siblingCount` pages on each side, and an ellipsis for each gap, so the number of buttons stays the same as the page moves and they don't jump under the pointer. `boundaryCount` sets how many pages stay at each end.

## Compact

`variant="compact"` shows Previous, "Page 3 of 10" and Next, for a narrow screen. `labels.status` rewords it.

```tsx live
import { Pagination } from 'patine-ui';

export default function Example() {
  return <Pagination pageCount={24} defaultPage={3} variant="compact" />;
}
```

## Designs

- **brand**: the current page filled with the primary color.
- **iOS**: the current page on a gray fill.
- **Material 3**: round page buttons, the current one filled.
- **web**: the current page outlined, the others ghost, as shadcn's Pagination.

## Accessibility

- A `navigation` landmark named `'Pagination'`. Each page is a button named `'Page 4'`; the current one is selected and `aria-current="page"`. Ellipses are hidden.
- Previous and Next are disabled at the ends. The compact text is announced as it changes.
- Buttons are 44pt on phones; on the web, Tab and the arrow keys move between them.
- Every word is in `labels`, for translation.

## Props

Also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pageCount` | `number` | — | How many pages there are. |
| `page` | `number` | — | The current page, from 1, controlled. |
| `defaultPage` | `number` | `1` | The first page when uncontrolled. |
| `onPageChange` | `(page: number) => void` | — | Called with the page the user goes to. |
| `siblingCount` | `number` | `1` | Pages each side of the current one. |
| `boundaryCount` | `number` | `1` | Pages always shown at each end. |
| `variant` | `'numbers' \| 'compact'` | `'numbers'` | Page buttons, or "Page 3 of 10". |
| `iconOnly` | `boolean` | `false` | Previous and Next as arrows only. |
| `disabled` | `boolean` | `false` | Disables every button. |
| `labels` | `{ nav, previous, next, page(n), status(n, count) }` | English | Every word, for translation. |
| `theme`, `design` | | | As every component. |
