> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/pagination.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/en/llms-full.txt.

# Pagination

Browse large datasets one page at a time.

## Basic usage

Buttons use outlines by default. Set `variant="ghost"` for borderless buttons.


Outline (default)

12345

Ghost

12345

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/pagination/basic.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationBasic() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Outline (default)</Text>
        <Pagination total={50} defaultCurrent={2} />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Ghost</Text>
        <Pagination total={50} defaultCurrent={2} variant="ghost" />
      </Space>
    </Space>
  );
}
```

Expand code

## Sizes

Compare small, default and large controls.


Small

123

Default

123

Large

123

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/pagination/sizes.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationSizes() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Small</Text>
        <Pagination total={30} defaultCurrent={2} size="sm" />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Default</Text>
        <Pagination total={30} defaultCurrent={2} size="md" />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Large</Text>
        <Pagination total={30} defaultCurrent={2} size="lg" />
      </Space>
    </Space>
  );
}
```

Expand code

## Controlled pagination

Control the page and page size together, with a total, size selector and quick jumper.


Total 240 items1234…24Go to

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/pagination/controlled.tsx"
import { Pagination } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function PaginationControlled() {
  const [pagination, setPagination] = useState({ current: 1, pageSize: 10 });

  return (
    <Pagination
      total={240}
      {...pagination}
      showTotal
      showSizeChanger
      showQuickJumper
      onChange={(current, pageSize) => setPagination({ current, pageSize })}
    />
  );
}
```

Expand code

## Simple and disabled

Use `simple` for previous/next controls and a page count. `disabled` blocks all interaction.


Simple

3 / 24

Disabled

12345

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/pagination/states.tsx"
import { Pagination, Space, Text } from '@ifhover/leaf-ui';

export function PaginationStates() {
  return (
    <Space direction="vertical" align="center" size="lg">
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Simple</Text>
        <Pagination total={240} defaultCurrent={3} simple />
      </Space>
      <Space direction="vertical" align="start" size="sm">
        <Text tone="muted">Disabled</Text>
        <Pagination total={50} defaultCurrent={2} disabled />
      </Space>
    </Space>
  );
}
```

Expand code

## Pagination API

| Property           | Type                                                                          | Default             | Description                                                                                       |
| ------------------ | ----------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `total`            | `number`                                                                      | Required            | Required. Total number of items.                                                                  |
| `current`          | `number`                                                                      | —                   | Controlled page, starting at 1.                                                                   |
| `defaultCurrent`   | `number`                                                                      | `1`                 | Initial page in uncontrolled mode.                                                                |
| `pageSize`         | `number`                                                                      | —                   | Controlled number of items per page.                                                              |
| `defaultPageSize`  | `number`                                                                      | `10`                | Initial page size in uncontrolled mode.                                                           |
| `onChange`         | `(page: number, pageSize: number) => void`                                    | —                   | Called once when the page or size actually changes, with both values.                             |
| `showSizeChanger`  | `boolean`                                                                     | `false`             | Show the page size selector.                                                                      |
| `pageSizeOptions`  | `readonly number[]`                                                           | `[10, 20, 50, 100]` | Available sizes; includes the current size, removes duplicates and ignores invalid values.        |
| `showQuickJumper`  | `boolean`                                                                     | `false`             | Commit on Enter or when leaving the pagination region; other pagination controls take precedence. |
| `showTotal`        | `boolean \| ((total: number, range: readonly [number, number]) => ReactNode)` | `false`             | true shows a localized total; pass a function for a custom total and visible item range.          |
| `simple`           | `boolean`                                                                     | `false`             | Show only previous/next controls and the current / total page count.                              |
| `disabled`         | `boolean`                                                                     | `false`             | Disable interaction.                                                                              |
| `hideOnSinglePage` | `boolean`                                                                     | `false`             | Hide when there are fewer than two pages.                                                         |
| `size`             | `'sm' \| 'md' \| 'lg'`                                                        | `'md'`              | Size of page buttons, size selector and jump input.                                               |
| `variant`          | `'outline' \| 'ghost'`                                                        | `'outline'`         | Button appearance: outlined or borderless.                                                        |

The component also accepts native `<nav>` attributes such as `aria-label`, `className` and `style`.

## Types

```ts
import type { PaginationProps } from '@ifhover/leaf-ui';
```

## Usage notes

Only `total` is required for basic use; uncontrolled pages and page sizes are managed internally. Use `current` and `pageSize` when loading remote data, and update both in `onChange`. Keep `total` equal to the full result count, rather than the number of items on the current page.

Changing page size preserves the current item position where possible. For example, page 3 at 10 items per page becomes page 2 at 20 items per page. Out-of-range pages are clamped; an empty dataset displays page 1 and disables both arrows. Changes to props do not emit `onChange`.

`showTotal` uses the nearest ConfigProvider language. To describe the visible range, pass a render function:

```tsx
<Pagination
  total={240}
  showTotal={(total, [start, end]) => `${start}–${end} / ${total} items`}
/>
```