# Pagination

Pagination in three forms: numbered pages, page dots that stretch as you swipe, and a Show more button that shows loading dots and marks the end of the list.

> Composed · Free · Navigation — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pagination
```

## Import

```tsx
import { PageDots, LoadMore, Pagination } from "@/components/ui/pagination/pagination";
```

## Variants

- `dots` — Dots: `npx @lumioui/cli add pagination-dots`
- `load-more` — Load more: `npx @lumioui/cli add pagination-load-more`
- `numbers` — Numbers: `npx @lumioui/cli add pagination-numbers`

## Props

### Pagination

| Prop | Type | Notes |
| --- | --- | --- |
| `total` | `number` | Total number of pages. |
| `page?` | `number` | Controlled current page (1-based). |
| `defaultPage?` | `number` | Uncontrolled initial page (1-based). Default 1. |
| `onPageChange?` | `(page: number) => void` | Fires with the new page when a number or arrow is tapped. |
| `siblings?` | `number` | Pages shown either side of the current one. Default 1. |
| `boundaries?` | `number` | Pages always shown at each end. Default 1. |
| `variant?` | `"numbers" | "compact"` | "numbers" — ‹ 1 … 4 5 6 … 12 › with a current-page disc that switches on in place. "compact" — ‹ Page 5 of 12 › for narrow rows and table footers. |
| `hideArrows?` | `boolean` | Hide the previous / next arrows. Default false. |
| `disabled?` | `boolean` | Disable every control. |
| `haptic?` | `boolean` | Haptic on page change. Default true. |
| `className?` | `string` | — |

### PageDots

| Prop | Type | Notes |
| --- | --- | --- |
| `count` | `number` | Number of pages. |
| `index?` | `number` | Current page (0-based). Used when `progress` isn't supplied. |
| `progress?` | `SharedValue<number>` | Continuous page position (0 … count-1) on the UI thread — e.g. scrollX / pageWidth from useAnimatedScrollHandler. The dots morph with the finger instead of snapping when the page settles. |
| `onIndexChange?` | `(index: number) => void` | Tap left / right of the active dot to step a page (page-control style). |
| `variant?` | `"pill" | "dot"` | "pill" — active dot stretches into a capsule. "dot" — classic page dots. Default "pill". |
| `tone?` | `"default" | "inverse"` | "default" ink on canvas, "inverse" white for dots over photos/video. |
| `className?` | `string` | — |

### LoadMore

| Prop | Type | Notes |
| --- | --- | --- |
| `onLoadMore?` | `() => void | Promise<unknown>` | Fetch the next page. Return a promise and the footer tracks loading itself. |
| `loading?` | `boolean` | Controlled loading state (otherwise derived from the onLoadMore promise). |
| `hasMore?` | `boolean` | More results exist. When false the footer settles into its end state. Default true. |
| `remaining?` | `number` | Items still to load — "Show 24 more" reads better than "Load more". |
| `label?` | `string` | Button label. Default "Show {remaining} more" or "Load more". |
| `endLabel?` | `string` | End-of-list line. Default "You're all caught up". |
| `variant?` | `"button" | "auto"` | "button" — a full-width secondary button (feeds, reviews). "auto" — busy-dots-only footer for FlatList `onEndReached` infinite lists. |
| `className?` | `string` | — |

## Icons rendered

- `check-circle` — /icons.html?i=check-circle
- `chevron-down` — /icons.html?i=chevron-down

Source: https://lumioui.com/components/pagination