Pagination

Browse large datasets one page at a time.

Basic usage

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

Outline (default)

Ghost

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>
  );
}

Sizes

Compare small, default and large controls.

Small

Default

Large

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>
  );
}

Controlled pagination

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

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 })}
    />
  );
}

Simple and disabled

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

Simple

Disabled

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>
  );
}

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

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:

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

#Pagination

#Basic usage

#Sizes

#Controlled pagination

#Simple and disabled

#Pagination API

#Types

#Usage notes