Pagination - Kumo

Showing 1-10 of 100

<Pagination
  page={page}
  setPage={setPage}
  perPage={10}
  totalCount={100}
/>

Installation

Barrel

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

Granular

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

Usage

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

Examples

Full Controls (Default)

The default pagination includes first, previous, page input, next, and last buttons.

Showing 1-10 of 100

<Pagination
  page={page}
  setPage={setPage}
  perPage={10}
  totalCount={100}
  controls="full"
/>

Simple Controls

Use controls="simple" for a minimal pagination with only previous and next buttons.

Showing 1-10 of 100

<Pagination
  page={page}
  setPage={setPage}
  perPage={10}
  totalCount={100}
  controls="simple"
/>

Mid-Page State

Pagination in the middle of a dataset with all navigation enabled.

Showing 41-50 of 100

<Pagination
  page={5}
  setPage={setPage}
  perPage={10}
  totalCount={100}
/>

Large Dataset

Pagination handles large datasets with many pages.

Showing 1-25 of 1250

<Pagination
  page={1}
  setPage={setPage}
  perPage={25}
  totalCount={1250}
/>

Custom Text

You can set custom pagination text

Page 1 - showing 25 per page

<Pagination
  text={({perPage}) => `Showing ${perPage} per page!`}
  page={1}
  setPage={setPage}
  perPage={25}
  totalCount={100}
/>

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.

Page Size Selector

Add a dropdown to let users select the number of items per page.

Showing 1-25 of 500

Per page:

const [page, setPage] = useState(1);
const [perPage, setPerPage] = useState(25);

<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 />
</Pagination>

Custom Page Size Options

Customize the available page size options with the options prop. Defaults to [25, 50, 100, 250].

Showing 1-10 of 200

Per page:

<Pagination page={page} setPage={setPage} perPage={perPage} totalCount={200}>
  <Pagination.Info />
  <Pagination.Separator />
  <Pagination.PageSize
    value={perPage}
    onChange={(size) => {
      setPerPage(size);
      setPage(1);
    }}
    options={[10, 20, 50]}
  />
  <Pagination.Controls />
</Pagination>

Custom Info Text

Use a render function to customize the info text.

Page 1 of 4

<Pagination page={page} setPage={setPage} perPage={25} totalCount={100}>
  <Pagination.Info>
    {({ page, totalCount }) => `Page ${page} of ${Math.ceil((totalCount ?? 1) / 25)}`}
  </Pagination.Info>
  <Pagination.Controls />
</Pagination>

Custom Layout

Arrange components in any order. Here the page size selector is on the right.

Showing 1-25 of 500

Per page:

<Pagination page={page} setPage={setPage} perPage={perPage} totalCount={500}>
  <Pagination.Info />
  <div className="flex items-center gap-2">
    <Pagination.Controls />
    <Pagination.Separator />
    <Pagination.PageSize value={perPage} onChange={setPerPage} />
  </div>
</Pagination>

API Reference

Prop	Type	Default	Description
setPage*	`(page: number) => void`	-	Callback when page changes
page	`number`	-	Current page number (1-indexed).
perPage	`number`	-	Number of items displayed per page.
totalCount	`number`	-	Total number of items across all pages.
className	`string`	-	Additional CSS classes for the container
children	`ReactNode`	-	Compound component children for custom layouts. Use Pagination.Info, Pagination.PageSize, Pagination.Controls, and Pagination.Separator.
controls	`"full" \| "simple"`	`"full"`	-
text	`object`	-	-