Pagination

Page navigation controls with multiple display variants (numbered pages, count summary, compact label, or none).

Examples

Default

function Default() {
  const [page, setPage] = useState(1);
  return <Pagination onChange={setPage} page={page} totalPages={10} />;
}

Count Variant

function CountVariant() {
  const [page, setPage] = useState(1);
  return (
    <Pagination
      onChange={setPage}
      page={page}
      totalItems={95}
      variant="count"
    />
  );
}

Compact Variant

function CompactVariant() {
  const [page, setPage] = useState(1);
  return (
    <Pagination
      onChange={setPage}
      page={page}
      totalPages={10}
      variant="compact"
    />
  );
}

None Variant

function NoneVariant() {
  const [page, setPage] = useState(1);
  return (
    <Pagination
      onChange={setPage}
      page={page}
      totalPages={10}
      variant="none"
    />
  );
}

Small Size

function SmallSize() {
  const [page, setPage] = useState(1);
  return (
    <Pagination onChange={setPage} page={page} size="sm" totalPages={10} />
  );
}

Disabled

<Pagination isDisabled onChange={() => {}} page={3} totalPages={10} />

Unknown Total

function UnknownTotal() {
  const [page, setPage] = useState(1);
  return (
    <Pagination
      hasMore={page < 5}
      onChange={setPage}
      page={page}
      variant="none"
    />
  );
}

Many Pages

function ManyPages() {
  const [page, setPage] = useState(50);
  return <Pagination onChange={setPage} page={page} totalPages={100} />;
}

Custom Sibling Count

function CustomSiblingCount() {
  const [page, setPage] = useState(10);
  return (
    <Pagination
      onChange={setPage}
      page={page}
      siblingCount={2}
      totalPages={20}
    />
  );
}

Controlled

Current page: 1

function Controlled() {
  const [page, setPage] = useState(1);
  const totalPages = 10;
  return (
    <div style={{display: 'flex', flexDirection: 'column', gap: '1rem'}}>
      <div style={{display: 'flex', gap: '0.5rem', alignItems: 'center'}}>
        <span>Current page: {page}</span>
        <button onClick={() => setPage(1)} type="button">
          Reset
        </button>
        <button onClick={() => setPage(totalPages)} type="button">
          Go to last
        </button>
      </div>
      <Pagination onChange={setPage} page={page} totalPages={totalPages} />
    </div>
  );
}

API

Pagination

Page navigation controls with multiple display variants (numbered pages, count summary, compact label, or none).

When Variant 1

Prop	Type	Default	Description
`className`	`string`	—	Additional CSS class names applied to the navigation root.
`data-testid`	`string`	—	Test ID applied to the navigation root.
`hasMore`	`boolean`	—	Whether another page exists when the total page count is unknown.
`isDisabled`	`boolean`	`false`	Whether the pagination controls are disabled.
`label`	`string`	`'Pagination'`	Accessible label for the navigation landmark.
`onChange`*	`(page: number) => void`	—	Called when the page changes.
`page`*	`number`	—	Current page number, starting at 1.
`pageSize`	`number`	`10`	Number of items per page.
`ref`	`Ref<HTMLElement>`	—	Ref forwarded to the navigation root.
`siblingCount`	`number`	`1`	Number of page buttons to show on each side of the current page.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	Control size.
`style`	`CSSProperties`	—	Inline styles applied to the navigation root.
`variant`	`"none" \| "count" \| "pages" \| "compact"`	`'pages'`	Display variant.
`totalItems`*	`number`	—
`totalPages`	`never`	—

When Variant 2

Prop	Type	Default	Description
`className`	`string`	—	Additional CSS class names applied to the navigation root.
`data-testid`	`string`	—	Test ID applied to the navigation root.
`hasMore`	`boolean`	—	Whether another page exists when the total page count is unknown.
`isDisabled`	`boolean`	`false`	Whether the pagination controls are disabled.
`label`	`string`	`'Pagination'`	Accessible label for the navigation landmark.
`onChange`*	`(page: number) => void`	—	Called when the page changes.
`page`*	`number`	—	Current page number, starting at 1.
`pageSize`	`number`	`10`	Number of items per page.
`ref`	`Ref<HTMLElement>`	—	Ref forwarded to the navigation root.
`siblingCount`	`number`	`1`	Number of page buttons to show on each side of the current page.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	Control size.
`style`	`CSSProperties`	—	Inline styles applied to the navigation root.
`variant`	`"none" \| "count" \| "pages" \| "compact"`	`'pages'`	Display variant.
`totalItems`	`never`	—
`totalPages`*	`number`	—

When Variant 3

Prop	Type	Default	Description
`className`	`string`	—	Additional CSS class names applied to the navigation root.
`data-testid`	`string`	—	Test ID applied to the navigation root.
`hasMore`	`boolean`	—	Whether another page exists when the total page count is unknown.
`isDisabled`	`boolean`	`false`	Whether the pagination controls are disabled.
`label`	`string`	`'Pagination'`	Accessible label for the navigation landmark.
`onChange`*	`(page: number) => void`	—	Called when the page changes.
`page`*	`number`	—	Current page number, starting at 1.
`pageSize`	`number`	`10`	Number of items per page.
`ref`	`Ref<HTMLElement>`	—	Ref forwarded to the navigation root.
`siblingCount`	`number`	`1`	Number of page buttons to show on each side of the current page.
`size`	`"sm" \| "md" \| "lg"`	`'md'`	Control size.
`style`	`CSSProperties`	—	Inline styles applied to the navigation root.
`variant`	`"none" \| "count" \| "pages" \| "compact"`	`'pages'`	Display variant.
`totalItems`	`never`	—
`totalPages`	`never`	—