---
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 Heading from "~/components/docs/Heading.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  PaginationBasicDemo,
  PaginationSimpleDemo,
  PaginationFullDemo,
  PaginationMidPageDemo,
  PaginationLargeDatasetDemo,
  PaginationCustomTextDemo,
  PaginationPageSizeSelectorDemo,
  PaginationCustomPageSizeOptionsDemo,
  PaginationCompoundCustomInfoDemo,
  PaginationDropdownSelectorDemo,
  PaginationPageSizeRightDemo,
} from "~/components/demos/PaginationDemo";

{/* Hero Demo */}

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

{/* Installation */}

<ComponentSection>
  <Heading level={2}>Installation</Heading>
  <Heading level={3}>Barrel</Heading>

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

<Heading level={3}>Granular</Heading>

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

</ComponentSection>

{/* Usage */}

<ComponentSection>
  <Heading level={2}>Usage</Heading>

```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>
  <Heading level={2}>Examples</Heading>

<Heading level={3}>Full Controls (Default)</Heading>
<p>
  The default pagination includes first, previous, page input, next, and last
  buttons.
</p>
<ComponentExample demo="PaginationFullDemo">
  <PaginationFullDemo client:visible />
</ComponentExample>

<Heading level={3}>Simple Controls</Heading>
<p>
  Use `controls="simple"` for a minimal pagination with only previous and next
  buttons.
</p>
<ComponentExample demo="PaginationSimpleDemo">
  <PaginationSimpleDemo client:visible />
</ComponentExample>

<Heading level={3}>Mid-Page State</Heading>
<p>Pagination in the middle of a dataset with all navigation enabled.</p>
<ComponentExample demo="PaginationMidPageDemo">
  <PaginationMidPageDemo client:visible />
</ComponentExample>

<Heading level={3}>Large Dataset</Heading>
<p>Pagination handles large datasets with many pages.</p>
<ComponentExample demo="PaginationLargeDatasetDemo">
  <PaginationLargeDatasetDemo client:visible />
</ComponentExample>

<Heading level={3}>Custom Text</Heading>
<p>You can set custom pagination text.</p>
<ComponentExample demo="PaginationCustomTextDemo">
  <PaginationCustomTextDemo client:visible />
</ComponentExample>

</ComponentSection>

{/* Compound Components */}

<ComponentSection>
  <Heading level={2}>Compound Components</Heading>
  <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>

<Heading level={3}>Page Size Selector</Heading>
<p>Add a dropdown to let users select the number of items per page.</p>
<ComponentExample demo="PaginationPageSizeSelectorDemo">
  <PaginationPageSizeSelectorDemo client:visible />
</ComponentExample>

<Heading level={3}>Custom Page Size Options</Heading>
<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>

<Heading level={3}>Custom Info Text</Heading>
<p>Use a render function to customize the info text.</p>
<ComponentExample demo="PaginationCompoundCustomInfoDemo">
  <PaginationCompoundCustomInfoDemo client:visible />
</ComponentExample>

<Heading level={3}>Custom Layout</Heading>
<p>
  Arrange components in any order. Here the page size selector is on the right.
</p>
<ComponentExample demo="PaginationPageSizeRightDemo">
  <PaginationPageSizeRightDemo client:visible />
</ComponentExample>

    <Heading level={3}>Dropdown Page Selector</Heading>
    <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>

{/* API Reference */}

<ComponentSection>
  <Heading level={2}>API Reference</Heading>
  <PropsTable component="Pagination" />
</ComponentSection>
