Navigation@knitui/components

Pagination

Pagination renders a row of page controls built from Pagination.Root + Pagination.Items + step/edge controls. Use the composite <Pagination> for the common case, or compose sub-components directly for custom layouts. size scales the control dimensions and typography. withEdges adds first/last jumps; withControls adds previous/next steps. grouped visually attaches every control into a single flush group (collapsed borders, only the outer corners rounded). Pass value + onChange for fully controlled behaviour.

WebiOSAndroid4 style slots23 own props11 examples

Stories Source Tests Open in Storybook

import { Pagination } from "@knitui/components";

Playground

Loading playground…

totalTotal number of pages.

sizeControls the dimensions of each page button.

withControlsShow previous / next step controls.

true

withEdgesShow first / last edge controls.

false

withPagesShow the numbered page controls.

true

groupedAttach all controls into a single flush group (collapsed borders).

false

disabledDisable the entire pagination.

false

hideWithOnePageHide entirely when total <= 1.

false

siblingsPages shown on each side of the active page.

boundariesPages always shown at the start and end.

radiusBorder-radius token applied to each control.

Playground

<Pagination
  total={10}
  defaultValue={1}
  size="md"
  withControls
  withEdges={false}
  withPages
  grouped={false}
  disabled={false}
  hideWithOnePage={false}
  siblings={1}
  boundaries={1}
/>

Examples

Sizes

All seven sizes rendered side-by-side, from xxs to xxl.

Loading example…

SizesSource Storybook

Shadows

Each elevation of the inherited shadow prop applied to the pagination row.

Loading example…

ShadowsSource Storybook

Disabled

Disabled state — all controls are dimmed and non-interactive.

Loading example…

DisabledSource Storybook

With Edges

Edge controls (first / last) are shown alongside prev / next.

Loading example…

With EdgesSource Storybook

Grouped

grouped attaches every control into a single flush group: gaps collapse, adjacent borders merge into a shared 1px line, and only the outer corners stay rounded — the same attached treatment as Button.Group / ActionIcon.Group.

Loading example…

GroupedSource Storybook

Siblings And Boundaries

Wider siblings and boundaries values reduce dots truncation.

Loading example…

Siblings And BoundariesSource Storybook

Custom Icons

Custom icons replace the default arrow glyphs on the step and edge controls.

Loading example…

Custom IconsSource Storybook

Controlled

Controlled — active page is owned by the parent component; current page is displayed.

Loading example…

ControlledSource Storybook

Compound API

Compound API — build a custom layout using Pagination.Root and its sub-components directly.

Loading example…

Compound APISource Storybook

Styles

Per-slot styles targets individual parts — here the item page controls and the control step controls.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`total` required	`number`	`10`	Total number of pages.
`boundaries`	`number \| undefined`	`1`	Pages always shown at the start and end.
`children`	`ReactNode`	—
`defaultValue`	`number \| undefined`	`1`	Uncontrolled initial active page (1-based).
`disabled` system	`boolean \| undefined`	`false`	Disable the entire pagination.
`dotsIcon`	`ReactNode`	—
`firstIcon`	`ReactNode`	—
`getControlProps`	`((control: PaginationControlType) => Partial<PaginationControlProps>) \| undefined`	—	Per-edge/step-control prop overrides (`first` / `previous` / `next` / `last`).
`getItemProps`	`((page: number) => Partial<PaginationControlProps>) \| undefined`	—	Per-page-control prop overrides.
`grouped`	`boolean \| undefined`	`false`	Attach all controls into a single flush group (collapsed borders).
`hideWithOnePage`	`boolean \| undefined`	`false`	Hide entirely when total <= 1.
`lastIcon`	`ReactNode`	—
`nextIcon`	`ReactNode`	—	Icon overrides for the step/edge/dots controls.
`onChange`	`((page: number) => void) \| undefined`	—	Called when the active page changes.
`onFirstPage`	`(() => void) \| undefined`	—	Called when the first-page control fires.
`onLastPage`	`(() => void) \| undefined`	—	Called when the last-page control fires.
`onNextPage`	`(() => void) \| undefined`	—	Called when the next-page control fires.
`onPreviousPage`	`(() => void) \| undefined`	—	Called when the previous-page control fires.
`previousIcon`	`ReactNode`	—
`radius` system	`string \| number \| undefined`	—	Border-radius token applied to each control.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`siblings`	`number \| undefined`	`1`	Pages shown on each side of the active page.
`size` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	`'md'`	Controls the dimensions of each page button.
`styles` system	`SlotStyles<PaginationStyles> \| undefined`	—	Per-slot style sugar — props spread onto the matching controls.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`value`	`number \| undefined`	—	Controlled active page (1-based).
`withControls`	`boolean \| undefined`	`true`	Show previous / next step controls.
`withEdges`	`boolean \| undefined`	`false`	Show first / last edge controls.
`withPages`	`boolean \| undefined`	`true`	Show the numbered page controls.

Style slots

Every part of Pagination can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`control`	`styles={{ control: { … } }}`
`dots`	`styles={{ dots: { … } }}`
`item`	`styles={{ item: { … } }}`
`root`	`styles={{ root: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 496 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.