---
layout: ~/layouts/MdxDocLayout.astro
title: "Pagination"
description: "A page navigation component for navigating through paginated content."
sourceFile: "components/pagination"
---

import ComponentExample from "~/components/docs/ComponentExample.astro";
import ComponentSection from "~/components/docs/ComponentSection.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  PaginationBasicDemo,
  PaginationSimpleDemo,
  PaginationFullDemo,
  PaginationMidPageDemo,
  PaginationLargeDatasetDemo,
  PaginationCustomTextDemo,
  PaginationPageSizeSelectorDemo,
  PaginationCustomPageSizeOptionsDemo,
  PaginationCompoundCustomInfoDemo,
  PaginationDropdownSelectorDemo,
  PaginationPageSizeRightDemo,
  PaginationI18nDemo,
} from "~/components/demos/PaginationDemo";

{/* Hero Demo */}

<ComponentSection>
  <ComponentExample demo="PaginationBasicDemo">
    <PaginationBasicDemo client:visible />
  </ComponentExample>
</ComponentSection>

{/* Installation */}

<ComponentSection>

## Installation

### Barrel

```tsx
import { Pagination } from "@cloudflare/kumo";
```

### Granular

```tsx
import { Pagination } from "@cloudflare/kumo/components/pagination";
```

</ComponentSection>

{/* Usage */}

<ComponentSection>

## Usage

```tsx
import { useState } from "react";
import { Pagination } from "@cloudflare/kumo";

export default function Example() {
  const [page, setPage] = useState(1);

  return (
    <Pagination page={page} setPage={setPage} perPage={10} totalCount={100} />
  );
}
```

</ComponentSection>

{/* Examples */}

<ComponentSection>

## Examples

### Full Controls (Default)

<p>
  The default pagination includes first, previous, page input, next, and last
  buttons.
</p>
<ComponentExample demo="PaginationFullDemo">
  <PaginationFullDemo client:visible />
</ComponentExample>

### Simple Controls

<p>
  Use `controls="simple"` for a minimal pagination with only previous and next
  buttons.
</p>
<ComponentExample demo="PaginationSimpleDemo">
  <PaginationSimpleDemo client:visible />
</ComponentExample>

### Mid-Page State

<p>Pagination in the middle of a dataset with all navigation enabled.</p>
<ComponentExample demo="PaginationMidPageDemo">
  <PaginationMidPageDemo client:visible />
</ComponentExample>

### Large Dataset

<p>Pagination handles large datasets with many pages.</p>
<ComponentExample demo="PaginationLargeDatasetDemo">
  <PaginationLargeDatasetDemo client:visible />
</ComponentExample>

### Custom Text

<p>You can set custom pagination text.</p>
<ComponentExample demo="PaginationCustomTextDemo">
  <PaginationCustomTextDemo client:visible />
</ComponentExample>

</ComponentSection>

{/* Compound Components */}

<ComponentSection>

## Compound Components

  <p>
    For more control over layout and features, use the compound component API. This allows you to compose `Pagination.Info`, `Pagination.PageSize`, `Pagination.Controls`, and `Pagination.Separator` in any order.
  </p>

### Page Size Selector

<p>Add a dropdown to let users select the number of items per page.</p>
<ComponentExample demo="PaginationPageSizeSelectorDemo">
  <PaginationPageSizeSelectorDemo client:visible />
</ComponentExample>

### Custom Page Size Options

<p>
  Customize the available page size options with the `options` prop. Defaults to
  `[25, 50, 100, 250]`.
</p>
<ComponentExample demo="PaginationCustomPageSizeOptionsDemo">
  <PaginationCustomPageSizeOptionsDemo client:visible />
</ComponentExample>

### Custom Info Text

<p>Use a render function to customize the info text.</p>
<ComponentExample demo="PaginationCompoundCustomInfoDemo">
  <PaginationCompoundCustomInfoDemo client:visible />
</ComponentExample>

### Custom Layout

<p>
  Arrange components in any order. Here the page size selector is on the right.
</p>
<ComponentExample demo="PaginationPageSizeRightDemo">
  <PaginationPageSizeRightDemo client:visible />
</ComponentExample>

### Dropdown Page Selector

    <p>
      Use `pageSelector="dropdown"` on `Pagination.Controls` to render a dropdown
      select instead of a text input for page navigation. This is useful when you
      want users to pick from a list of available pages rather than typing a number.
    </p>
    <ComponentExample
      code={`<Pagination page={page} setPage={setPage} perPage={perPage} totalCount={500}>

  <Pagination.Info />
  <Pagination.Separator />
  <Pagination.PageSize
    value={perPage}
    onChange={(size) => {
      setPerPage(size);
      setPage(1);
    }}
  />
  <Pagination.Controls pageSelector="dropdown" />
</Pagination>`}
    >
      <PaginationDropdownSelectorDemo client:visible />
    </ComponentExample>
</ComponentSection>

{/* Internationalization */}

<ComponentSection>

## Internationalization

  <p>
    Use the `labels` prop to customize all UI strings for different locales. All labels default to English.
  </p>

<ComponentExample demo="PaginationI18nDemo">
  <PaginationI18nDemo client:visible />
</ComponentExample>

</ComponentSection>

{/* API Reference */}

<ComponentSection>

## API Reference

  <PropsTable component="Pagination" />
</ComponentSection>
