For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/pagination.md.

Pagination

Browse large datasets one page at a time.

Basic usage

Set total to the full result count, not the number of items on the current page. Pages start at 1; uncontrolled pagination manages the current page internally.

basic.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationBasic() {
  return <Pagination total={50} />;
}

Out-of-range pages are clamped. With total={0}, page 1 is still displayed and both arrows are disabled.

Examples

Button appearance

Use variant to choose outlined or borderless pagination buttons.

Outline (default)
Ghost
variants.tsx
import { Flex, Grid, Pagination, Text } from '@ifhover/leaf-ui';

export function PaginationVariants() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">Outline (default)</Text>
        <Pagination aria-label="Outline pagination" total={30} defaultCurrent={2} />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">Ghost</Text>
        <Pagination aria-label="Ghost pagination" total={30} defaultCurrent={2} variant="ghost" />
      </Flex>
    </Grid>
  );
}

Sizes

Use size to set the pagination button size.

Small
Medium (default)
Large
sizes.tsx
import { Flex, Grid, Pagination, Text } from '@ifhover/leaf-ui';

export function PaginationSizes() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">Small</Text>
        <Pagination aria-label="Small pagination" total={30} defaultCurrent={2} size="sm" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">Medium (default)</Text>
        <Pagination aria-label="Medium pagination" total={30} defaultCurrent={2} size="md" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">Large</Text>
        <Pagination aria-label="Large pagination" total={30} defaultCurrent={2} size="lg" />
      </Flex>
    </Grid>
  );
}

Controlled pagination

For remote data, control current and pageSize together and update both in onChange. The application sends the data request; this example displays the current page and item range as feedback.

Page 1, 10 items per page
controlled.tsx
import { Flex, Pagination, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

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

  return (
    <Flex direction="column" gap={16}>
      <Pagination
        total={240}
        {...pagination}
        showTotal={(total, [start, end]) => `${start}-${end} of ${total} items`}
        showSizeChanger
        showQuickJumper
        onChange={(current, pageSize) => setPagination({ current, pageSize })}
      />
      <Text tone="muted" role="status">
        Page {pagination.current}, {pagination.pageSize} items per page
      </Text>
    </Flex>
  );
}

Changing page size preserves the current item position where possible: page 3 at 10 items per page becomes page 2 at 20 items per page. Changes to props do not emit onChange.

Simple mode

Set simple to show the current page and previous/next controls.

simple.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationSimple() {
  return <Pagination total={240} defaultCurrent={3} simple />;
}

Disabled

Use disabled to prevent page changes.

states.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationStates() {
  return <Pagination total={50} defaultCurrent={2} disabled />;
}

API

Pagination API

Configure the total item count, current page, page size and pagination interaction.

PropertyTypeDefaultDescription
totalnumberRequiredTotal number of items.
currentnumber—Controlled page, starting at 1.
defaultCurrentnumber1Initial page in uncontrolled mode.
pageSizenumber—Controlled number of items per page.
defaultPageSizenumber10Initial page size in uncontrolled mode.
onChange(page: number, pageSize: number) => void—Called once when the page or size actually changes, with both values.
showSizeChangerbooleanfalseShow the page size selector.
pageSizeOptionsreadonly number[][10, 20, 50, 100]Available sizes; includes the current size, removes duplicates and ignores invalid values.
showQuickJumperbooleanfalseCommit on Enter or when leaving the pagination region; other pagination controls take precedence.
showTotalboolean | ((total: number, range: readonly [number, number]) => ReactNode)falsetrue shows a localized total; pass a function for a custom total and visible item range.
simplebooleanfalseShow only previous/next controls and the current / total page count.
disabledbooleanfalseDisable interaction.
hideOnSinglePagebooleanfalseHide 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.