Pagination

A navigation component for splitting content into multiple pages, often used in tables, lists, or galleries.

Usage

Basic usage example to quickly see how the Pagination component works. This demonstration provides a quick overview of how the pagination mechanism is implemented and interacted with.

import { Pagination } from "@/ui/pagination";

export function PaginationDemo() {
  return <Pagination total={16} defaultValue={11} />;
}

Interactive configurator to explore various customization options for the Pagination component. You can adjust settings such as the total number of pages, current active page, boundary counts, sibling counts, and more.

Sibling

Boundaries

Color

With edges

Pagination As Link

Demonstration of rendering pagination items as links. This example shows how pagination buttons can be transformed into navigable links, useful for applications with route-based navigation (e.g., Next.js routing).

Regular ComponentComposite Component

"use client";
import React from "react";
import { Typography } from "@/ui/typography";
import { Pagination, PaginationFirst, PaginationItems, PaginationLast, PaginationNext, PaginationPrevious } from "@/ui/pagination";

export function PaginationAsLinkDemo() {
  const [activePage, setPage] = React.useState(8);
  const lastPage = 15;

  const getHrefForControl = (control: string, currentPage: number): string => {
    switch (control) {
      case "first":
        return `#page-1`;
      case "previous":
        return `#page-${Math.max(1, currentPage - 1)}`;
      case "next":
        return `#page-${Math.min(lastPage, currentPage + 1)}`;
      case "last":
        return `#page-${lastPage}`;
      default:
        return "#";
    }
  };
  return (
    <div className="m-auto size-full">
      <Typography prose="span">Regular Component</Typography>
      <Pagination
        withEdges
        total={lastPage}
        value={activePage}
        onChange={page => setTimeout(() => setPage(page), 150)}
        getItemProps={page => ({
          el: "a",
          href: `#page-${page}`
        })}
        getControlProps={control => ({
          el: "a",
          href: getHrefForControl(control, activePage)
        })}
      />

      <Typography prose="span">Composite Component</Typography>
      <Pagination
        total={10}
        getItemProps={page => ({
          el: "a",
          href: `#page-${page}`
        })}
      >
        <PaginationFirst el="a" href="#page-0" />
        <PaginationPrevious el="a" href="#page-1" />
        <PaginationItems />
        <PaginationNext el="a" href="#page-2" />
        <PaginationLast el="a" href="#page-10" />
      </Pagination>
    </div>
  );
}

Pagination Change Icons

Customize the pagination navigation icons. Here you can see how to replace the default navigation icons (previous, next, first, last) with custom icons according to your design needs.

Regular ComponentComposite Component

import React from "react";
import { Pagination } from "@/ui/pagination";
import { Typography } from "@/ui/typography";
import { ArrowSquareRoundRightIcon, ArrowSquareRoundLeftIcon, ChevronCircleRightIcon, ChevronCircleLeftIcon } from "@/icons/*";
import { Svg } from "@/ui/svg";

function Dot() {
  return (
    <Svg>
      <circle cx="12.1" cy="12.1" r="1" />
    </Svg>
  );
}

export function PaginationChangeIconsDemo() {
  return (
    <div className="m-auto size-full">
      <Typography prose="span">Regular Component</Typography>
      <Pagination
        siblings={2}
        boundaries={2}
        withEdges
        total={15}
        defaultValue={8}
        icons={{
          first: ArrowSquareRoundLeftIcon,
          previous: ChevronCircleLeftIcon,
          next: ChevronCircleRightIcon,
          last: ArrowSquareRoundRightIcon,
          dots: Dot
        }}
      />

      <Typography prose="span">Composite Component</Typography>
      <Pagination siblings={2} boundaries={2} total={15} defaultValue={8}>
        <Pagination.First icon={ArrowSquareRoundLeftIcon} />
        <Pagination.Previous icon={ChevronCircleLeftIcon} />
        <Pagination.Items dotsIcon={Dot} />
        <Pagination.Next icon={ChevronCircleRightIcon} />
        <Pagination.Last icon={ArrowSquareRoundRightIcon} />
      </Pagination>
    </div>
  );
}

Pagination With Chunked Content

Paginate dynamically loaded or chunked content. This example demonstrates how to divide a large dataset or long content into smaller pages, providing a smoother user experience with pagination controls.

"use client";
import { useState } from "react";
import { Pagination } from "@/ui/pagination";
import { dataRenderer, Table } from "@/ui/table";
import { Stack } from "@/ui/stack";

function randomId() {
  return `${Math.random().toString(36).slice(2, 11)}`;
}
function chunk<T>(array: T[], size: number): T[][] {
  if (!array.length) {
    return [];
  }
  const head = array.slice(0, size);
  const tail = array.slice(size);
  return [head, ...chunk(tail, size)];
}

const data = chunk(
  Array(30)
    .fill(0)
    .map((_, index) => ({ id: index, name: randomId() })),
  5
);

export function PaginationWithChunkedContentDemo() {
  const [activePage, setPage] = useState(1);

  const tableData = {
    head: ["ID", "NAME"],
    body: dataRenderer(data[activePage - 1], [
      (item) => item.id + 1,
      (item) => item.name,
    ])
  }

  return (
    <Stack>
      <Table data={tableData} />
      <Pagination total={data.length} value={activePage} onChange={setPage} />
    </Stack>
  );
}

Controlled

To control component state provide value and onChange props:

"use client";
import { useState } from "react";
import { Pagination } from "@/ui/pagination";
 
function ControlledPagination() {
  const [activePage, setPage] = useState(1);
  return <Pagination value={activePage} onChange={setPage} total={10} />;
}

Structure

Independent Components

import { Pagination, PaginationFirst, PaginationItems, PaginationLast, PaginationNext, PaginationPrevious } from "@/ui/pagination";
 
export function PaginationDemo() {
  const itemsProps = (page: number) => ({ el: "a", href: `#page-${page}` });
  return (
    <Pagination total={10} getItemProps={itemsProps}>
      <PaginationFirst el="a" href="#page-0" />
      <PaginationPrevious el="a" href="#page-1" />
      <PaginationItems />
      <PaginationNext el="a" href="#page-2" />
      <PaginationLast el="a" href="#page-10" />
    </Pagination>
  );
}

Compound Components

"use client";
import { Pagination } from "@/ui/pagination";
import { ArrowSquareRoundRightIcon, ArrowSquareRoundLeftIcon, ChevronCircleRightIcon, ChevronCircleLeftIcon, Svg } from "@/icons/*";
 
export function PaginationDemo() {
  return (
    <Pagination siblings={2} boundaries={2} total={15} defaultValue={8}>
      <Pagination.First icon={ArrowSquareRoundLeftIcon} />
      <Pagination.Previous icon={ChevronCircleLeftIcon} />
      <Pagination.Items dotsIcon={Dot} />
      <Pagination.Next icon={ChevronCircleRightIcon} />
      <Pagination.Last icon={ArrowSquareRoundRightIcon} />
    </Pagination>
  );
}

Declarative Props API

import { Pagination } from "@/ui/pagination";
 
export function PaginationDemo() {
  return <Pagination siblings={2} boundaries={2} withEdges color="orange" total={21} defaultValue={11} />;
}

API References

Styles API

type T = "root" | "control" | "dots";

Styles API	Type	Default	Annotation
unstyled`?`	`Partial<Record<T, boolean>>`	`false`	if `true`, default styles will be removed
className`?`	`string`	`undefined`	pass to root component `<div>`
classNames`?`	`Partial<Record<T, string>>`	`undefined`
style`?`	`CSSProperties`	`undefined`	pass to root component `<div>`
styles`?`	`Partial<Record<T, CSSProperties>>`	`undefined`

Props API

type Icons = { first?: PaginationIcon; previous?: PaginationIcon; next?: PaginationIcon; last?: PaginationIcon; dots?: PaginationIcon };
 
type Control = "first" | "previous" | "next" | "last";

Props API	Type	Default	Annotation
icons`?`	`Icons`	`default`	Control icons component
gap`?`	`string\| number`	`8`	Key of gap between controls
size`?`	`(string & {}) \| number`	`32`	`height` and `min-width` of controls
total	`number`	`-`	Total number of pages, must be an integer
color`?`	`Property.Color`	`undefined`	Key of `colors, active item color
value`?`	`number`	`undefined`	Active page for controlled component, must be an integer in [0, total] interval
defaultValue`?`	`number`	`undefined`	Active page for uncontrolled component, must be an integer in [0, total] interval
disabled`?`	`boolean`	`false`	Determines whether all controls should be disabled
hideWithOnePage`?`	`boolean`	`false`	Determines whether pagination should be hidden when only one page is available `total={1}`
withEdges`?`	`boolean`	`false`	Determines whether first/last controls should be rendered
withControls`?`	`boolean`	`true`	Determines whether next/previous controls should be rendered
siblings`?`	`number`	`1`	Number of siblings displayed on the left/right side of the selected page
boundaries`?`	`number`	`1`	Number of elements visible on the left/right edges
onNextPage`?`	`() => void`	`undefined`	Called when next page control is clicked
onPreviousPage`?`	`() => void`	`undefined`	Called when previous page control is clicked
onFirstPage`?`	`() => void`	`undefined`	Called when first page control is clicked
onLastPage`?`	`() => void`	`undefined`	Called when last page control is clicked
onChange`?`	`(page: number) => void`	`undefined`	Called when page changes
getItemProps`?`	`(page: number) => Record<string, any>`	`undefined`	Additional props passed down to controls
getControlProps`?`	`(control: Control) => Record<string, any>`	`undefined`	Adds props to next/previous/first/last controls

Source Codes

Full working code example, including necessary markup and styles. You can copy and paste this code directly to start using the component immediately.

pagination.tsx

Pagination

A navigation component for splitting content into multiple pages, often used in tables, lists, or galleries.

Usage

Basic usage example to quickly see how the Pagination component works. This demonstration provides a quick overview of how the pagination mechanism is implemented and interacted with.

import { Pagination } from "@/ui/pagination";

export function PaginationDemo() {
  return <Pagination total={16} defaultValue={11} />;
}

Properties

Sibling

Boundaries

Color

With edges

Pagination As Link

Regular ComponentComposite Component

"use client";
import React from "react";
import { Typography } from "@/ui/typography";
import { Pagination, PaginationFirst, PaginationItems, PaginationLast, PaginationNext, PaginationPrevious } from "@/ui/pagination";

export function PaginationAsLinkDemo() {
  const [activePage, setPage] = React.useState(8);
  const lastPage = 15;

  const getHrefForControl = (control: string, currentPage: number): string => {
    switch (control) {
      case "first":
        return `#page-1`;
      case "previous":
        return `#page-${Math.max(1, currentPage - 1)}`;
      case "next":
        return `#page-${Math.min(lastPage, currentPage + 1)}`;
      case "last":
        return `#page-${lastPage}`;
      default:
        return "#";
    }
  };
  return (
    <div className="m-auto size-full">
      <Typography prose="span">Regular Component</Typography>
      <Pagination
        withEdges
        total={lastPage}
        value={activePage}
        onChange={page => setTimeout(() => setPage(page), 150)}
        getItemProps={page => ({
          el: "a",
          href: `#page-${page}`
        })}
        getControlProps={control => ({
          el: "a",
          href: getHrefForControl(control, activePage)
        })}
      />

      <Typography prose="span">Composite Component</Typography>
      <Pagination
        total={10}
        getItemProps={page => ({
          el: "a",
          href: `#page-${page}`
        })}
      >
        <PaginationFirst el="a" href="#page-0" />
        <PaginationPrevious el="a" href="#page-1" />
        <PaginationItems />
        <PaginationNext el="a" href="#page-2" />
        <PaginationLast el="a" href="#page-10" />
      </Pagination>
    </div>
  );
}

Pagination Change Icons

Customize the pagination navigation icons. Here you can see how to replace the default navigation icons (previous, next, first, last) with custom icons according to your design needs.

Regular ComponentComposite Component

import React from "react";
import { Pagination } from "@/ui/pagination";
import { Typography } from "@/ui/typography";
import { ArrowSquareRoundRightIcon, ArrowSquareRoundLeftIcon, ChevronCircleRightIcon, ChevronCircleLeftIcon } from "@/icons/*";
import { Svg } from "@/ui/svg";

function Dot() {
  return (
    <Svg>
      <circle cx="12.1" cy="12.1" r="1" />
    </Svg>
  );
}

export function PaginationChangeIconsDemo() {
  return (
    <div className="m-auto size-full">
      <Typography prose="span">Regular Component</Typography>
      <Pagination
        siblings={2}
        boundaries={2}
        withEdges
        total={15}
        defaultValue={8}
        icons={{
          first: ArrowSquareRoundLeftIcon,
          previous: ChevronCircleLeftIcon,
          next: ChevronCircleRightIcon,
          last: ArrowSquareRoundRightIcon,
          dots: Dot
        }}
      />

      <Typography prose="span">Composite Component</Typography>
      <Pagination siblings={2} boundaries={2} total={15} defaultValue={8}>
        <Pagination.First icon={ArrowSquareRoundLeftIcon} />
        <Pagination.Previous icon={ChevronCircleLeftIcon} />
        <Pagination.Items dotsIcon={Dot} />
        <Pagination.Next icon={ChevronCircleRightIcon} />
        <Pagination.Last icon={ArrowSquareRoundRightIcon} />
      </Pagination>
    </div>
  );
}

Pagination With Chunked Content

"use client";
import { useState } from "react";
import { Pagination } from "@/ui/pagination";
import { dataRenderer, Table } from "@/ui/table";
import { Stack } from "@/ui/stack";

function randomId() {
  return `${Math.random().toString(36).slice(2, 11)}`;
}
function chunk<T>(array: T[], size: number): T[][] {
  if (!array.length) {
    return [];
  }
  const head = array.slice(0, size);
  const tail = array.slice(size);
  return [head, ...chunk(tail, size)];
}

const data = chunk(
  Array(30)
    .fill(0)
    .map((_, index) => ({ id: index, name: randomId() })),
  5
);

export function PaginationWithChunkedContentDemo() {
  const [activePage, setPage] = useState(1);

  const tableData = {
    head: ["ID", "NAME"],
    body: dataRenderer(data[activePage - 1], [
      (item) => item.id + 1,
      (item) => item.name,
    ])
  }

  return (
    <Stack>
      <Table data={tableData} />
      <Pagination total={data.length} value={activePage} onChange={setPage} />
    </Stack>
  );
}

Controlled

To control component state provide value and onChange props:

"use client";
import { useState } from "react";
import { Pagination } from "@/ui/pagination";
 
function ControlledPagination() {
  const [activePage, setPage] = useState(1);
  return <Pagination value={activePage} onChange={setPage} total={10} />;
}

Structure

Independent Components

import { Pagination, PaginationFirst, PaginationItems, PaginationLast, PaginationNext, PaginationPrevious } from "@/ui/pagination";
 
export function PaginationDemo() {
  const itemsProps = (page: number) => ({ el: "a", href: `#page-${page}` });
  return (
    <Pagination total={10} getItemProps={itemsProps}>
      <PaginationFirst el="a" href="#page-0" />
      <PaginationPrevious el="a" href="#page-1" />
      <PaginationItems />
      <PaginationNext el="a" href="#page-2" />
      <PaginationLast el="a" href="#page-10" />
    </Pagination>
  );
}

Compound Components

"use client";
import { Pagination } from "@/ui/pagination";
import { ArrowSquareRoundRightIcon, ArrowSquareRoundLeftIcon, ChevronCircleRightIcon, ChevronCircleLeftIcon, Svg } from "@/icons/*";
 
export function PaginationDemo() {
  return (
    <Pagination siblings={2} boundaries={2} total={15} defaultValue={8}>
      <Pagination.First icon={ArrowSquareRoundLeftIcon} />
      <Pagination.Previous icon={ChevronCircleLeftIcon} />
      <Pagination.Items dotsIcon={Dot} />
      <Pagination.Next icon={ChevronCircleRightIcon} />
      <Pagination.Last icon={ArrowSquareRoundRightIcon} />
    </Pagination>
  );
}

Declarative Props API

import { Pagination } from "@/ui/pagination";
 
export function PaginationDemo() {
  return <Pagination siblings={2} boundaries={2} withEdges color="orange" total={21} defaultValue={11} />;
}

API References

Styles API

type T = "root" | "control" | "dots";

Styles API	Type	Default	Annotation
unstyled`?`	`Partial<Record<T, boolean>>`	`false`	if `true`, default styles will be removed
className`?`	`string`	`undefined`	pass to root component `<div>`
classNames`?`	`Partial<Record<T, string>>`	`undefined`
style`?`	`CSSProperties`	`undefined`	pass to root component `<div>`
styles`?`	`Partial<Record<T, CSSProperties>>`	`undefined`

Props API

type Icons = { first?: PaginationIcon; previous?: PaginationIcon; next?: PaginationIcon; last?: PaginationIcon; dots?: PaginationIcon };
 
type Control = "first" | "previous" | "next" | "last";

Props API	Type	Default	Annotation
icons`?`	`Icons`	`default`	Control icons component
gap`?`	`string\| number`	`8`	Key of gap between controls
size`?`	`(string & {}) \| number`	`32`	`height` and `min-width` of controls
total	`number`	`-`	Total number of pages, must be an integer
color`?`	`Property.Color`	`undefined`	Key of `colors, active item color
value`?`	`number`	`undefined`	Active page for controlled component, must be an integer in [0, total] interval
defaultValue`?`	`number`	`undefined`	Active page for uncontrolled component, must be an integer in [0, total] interval
disabled`?`	`boolean`	`false`	Determines whether all controls should be disabled
hideWithOnePage`?`	`boolean`	`false`	Determines whether pagination should be hidden when only one page is available `total={1}`
withEdges`?`	`boolean`	`false`	Determines whether first/last controls should be rendered
withControls`?`	`boolean`	`true`	Determines whether next/previous controls should be rendered
siblings`?`	`number`	`1`	Number of siblings displayed on the left/right side of the selected page
boundaries`?`	`number`	`1`	Number of elements visible on the left/right edges
onNextPage`?`	`() => void`	`undefined`	Called when next page control is clicked
onPreviousPage`?`	`() => void`	`undefined`	Called when previous page control is clicked
onFirstPage`?`	`() => void`	`undefined`	Called when first page control is clicked
onLastPage`?`	`() => void`	`undefined`	Called when last page control is clicked
onChange`?`	`(page: number) => void`	`undefined`	Called when page changes
getItemProps`?`	`(page: number) => Record<string, any>`	`undefined`	Additional props passed down to controls
getControlProps`?`	`(control: Control) => Record<string, any>`	`undefined`	Adds props to next/previous/first/last controls

Source Codes

Full working code example, including necessary markup and styles. You can copy and paste this code directly to start using the component immediately.

Pagination

Usage

Properties

Controlled

Structure

Independent Components

Compound Components

Declarative Props API

API References

Styles API

Props API

Source Codes

pagination.tsx

globals.css

Pagination

Usage

Properties

Controlled

Structure

Independent Components

Compound Components

Declarative Props API

API References

Styles API

Props API

Source Codes

pagination.tsx

globals.css