Pagination

The Pagination component provides a compact page navigation UI (Prev/Next + page numbers + optional placeholders) and works well with controlled state.

Props

Name	Type	Default	Provider?	Description
`page`	`number`	`1`	No	Current page (1-based).
`totalPages`	`number`	—	No	Total number of pages. If `< 1`, the component renders nothing.
`onChange`	`(page: number) => void`	—	No	Called when the user changes page (Prev/Next or clicking a page number).
`seblings`	`number`	`1`	Yes	How many pages to show around the current page.
`disabled`	`boolean`	—	No	Disables all buttons and prevents navigation.
`placeholderIcon`	`ReactNode`	`"..."`	Yes	Custom icon/content for placeholder buttons.
`prevIcon`	`ReactNode`	`"Prev"`	Yes	Custom icon/content for the previous button.
`nextIcon`	`ReactNode`	`"Next"`	Yes	Custom icon/content for the next button.

Note Props marked with Yes in the Provider? column can be configured globally using the ComponentPropsProvider.

Usage

Quick start

import React, { useState } from "react";
import { Pagination } from "@kousta-ui/components";

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

return (
  <div style={{ width: "100%" }}>
    <Pagination page={page} totalPages={10} onChange={setPage} />
  </div>
);
}

seblings

Use seblings to show more pages around the current page.

import React, { useState } from "react";
import { Pagination } from "@kousta-ui/components";

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

return (
  <div style={{ width: "100%" }}>
    <Pagination page={page} totalPages={20} onChange={setPage} seblings={2} />
  </div>
);
}

Disabled

import { Pagination } from "@kousta-ui/components";

export function Example() {
return (
  <div style={{ width: "100%" }}>
    <Pagination page={1} totalPages={10} disabled />
  </div>
);
}

Icons

You can override the built-in content of the control buttons and placeholders.

Override icons on a single Pagination

import React, { useState } from "react";
import { Pagination } from "@kousta-ui/components";
import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";

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

return (
  <div style={{ width: "100%" }}>
    <Pagination
      page={page}
      totalPages={20}
      onChange={setPage}
      prevIcon={<ChevronLeft size={16} />}
      nextIcon={<ChevronRight size={16} />}
      placeholderIcon={<MoreHorizontal size={16} />}
      seblings={1}
    />
  </div>
);
}

Override icons with ComponentPropsProvider

import React, { useState } from "react";
import { ComponentPropsProvider, Pagination } from "@kousta-ui/components";
import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";

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

return (
  <ComponentPropsProvider
    pagination={{
      prevIcon: <ChevronLeft size={16} />,
      nextIcon: <ChevronRight size={16} />,
      placeholderIcon: <MoreHorizontal size={16} />,
      seblings: 1,
    }}
  >
    <div style={{ width: "100%" }}>
      <Pagination page={page} totalPages={20} onChange={setPage} />
    </div>
  </ComponentPropsProvider>
);
}

With usePagination

If you want the logic (total pages, boundaries, setters) handled for you, use the usePagination hook.

import { Pagination } from "@kousta-ui/components";
import { usePagination } from "@kousta-ui/hooks";

export function Example() {
const { page, totalPages, setPage } = usePagination({ total: 240, limit: 20 });

return (
  <div style={{ width: "100%" }}>
    <Pagination page={page} totalPages={totalPages} onChange={setPage} />
  </div>
);
}

Code review

Controlled vs internal state: Pagination keeps an internal currentPage state for UI, and syncs it when the page prop changes.
Boundaries: Prev/Next are disabled at 1 and totalPages (and everything is disabled when disabled is true).
Page calculation: The component uses seblings and the getSeblings helper to compute which page numbers to show. It inserts placeholders ("") which render as disabled buttons showing placeholderIcon (or "...").
Provider overrides: ComponentPropsProvider can override placeholderIcon, nextIcon, prevIcon, and seblings. Local props win when provided.

Accessibility

Labels: Provide accessible labels for icon-only pagination controls (for example via prevIcon / nextIcon content or by wrapping with aria-label at the button level if you override rendering).
Current page: Ensure the active page is clearly indicated visually (the component applies kui-pagination-active-link).
Keyboard: Pagination controls are buttons/links and are keyboard reachable by default; test Tab order when embedding in complex toolbars.

Styles & customization

Runtime classes

kui-pagination-link: Applied to all clickable controls (Prev/Next + page buttons).
kui-pagination-active-link: Applied to the active page.
kui-pagination-placeholder: Applied to placeholder buttons.

Types (reference)


import { ReactNode } from "react";
 
export type PaginationProps = {
  page: number;
  onChange?: (page: number) => void;
  totalPages: number;
  seblings?: number;
  disabled?: boolean;
 
  placeholderIcon?: ReactNode;
  nextIcon?: ReactNode;
  prevIcon?: ReactNode;
};