Pagination

import { Pagination } from '@yarcl/react';

1…567…20

Page 6 of 20

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

<Pagination count={20} page={page} onPageChange={setPage} aria-label="Search results" />

Pass page and onPageChange to control it, or defaultPage to let it keep its own state. Pages start at 1.

Compact layout

Set layout="compact" to show a page summary at the start and previous and next buttons at the end. The control fills its available width, keeping the buttons at the right edge in left-to-right layouts. Right-to-left layouts mirror the arrangement and arrow direction.

Page 3 of 20

const [page, setPage] = useState(3);

<Pagination
  layout="compact"
  count={20}
  page={page}
  onPageChange={setPage}
  aria-label="Search results"
/>

summaryLabel={(page, count) => `${page} / ${count}`} customizes the summary for your language or format. Its status region announces updates politely. With no pages it shows “Page 0 of 0” and both arrows are unavailable. variant, size, color, radius, attached and disabled also apply to compact controls.

The default layout="numbered" renders page buttons and ellipses. siblings, boundaries, pageLabel and selectedVariant apply to that layout.

Siblings and boundaries

siblings sets how many pages show on each side of the current one, and boundaries how many always show at the start and end. Skipped ranges collapse into an ellipsis. The number of buttons stays the same as you move, so the control doesn’t jump around.

Styles

Buttons use the shared size scale, so a pagination lines up with a Button or Input of the same size. Other pages and the previous and next buttons use variant (the config’s softVariant by default), and the current page uses selectedVariant (the default variant), like ToggleGroup. Set attached to join the buttons into one control, like ButtonGroup. Set defaults for every pagination in components.Pagination.

12345…10

12…2324252627…4950

12345

<Pagination count={10} attached variant="outline" selectedVariant="solid" color="neutral" />
<Pagination count={50} siblings={2} boundaries={2} size="sm" />
<Pagination count={5} radius="rounded" variant="ghost" />

Accessibility

Renders a <nav> landmark named by aria-label (default “Pagination”); give each pagination on a page its own name. In the numbered layout, the current page has aria-current="page". The compact layout exposes its current page in a live status region. Page buttons are announced as “Page 3” and the arrows as “Previous page” and “Next page”; change these with pageLabel, previousLabel and nextLabel. On the first or last page the previous or next button stays focusable with aria-disabled, so focus isn’t lost. Ellipses are hidden from screen readers.

Keyboard

Key	Action
Tab	moves through the buttons
← →	moves focus to the previous or next button
Home End	moves focus to the first or last button
Enter Space	goes to the focused page

Props

Prop	Type	Default	Description
count required	number		Total number of pages.
aria-label	string	'Pagination'	Accessible name of the navigation landmark.
attached	boolean	false	Joins the buttons into one control with shared borders.
boundaries	number	1	Pages always shown at the start and end in the numbered layout.
color	Colorconfig		Color of every button, from the colors config.
defaultPage	number	1	Initial page when uncontrolled.
disabled	boolean		Disables every button.
layout	'compact' | 'numbered'	'numbered'	Shows numbered page buttons or a summary with previous and next buttons at the inline end.
nextLabel	string	config.labels.nextPage	Accessible name of the next button.
onPageChange	(page: number) => void		Called with the new page when the user picks one.
page	number		Controlled current page, starting at 1.
pageLabel	(page: number) => string	config.labels.page	Accessible name of each page button.
previousLabel	string	config.labels.previousPage	Accessible name of the previous button.
radius	'size' | Radiusconfig		Radius of every button, from the radii config, or 'size' to match the button size.
selectedVariant	Variantconfig	config.defaults.variant	Variant of the current page in the numbered layout, from this component's variant map or shared variants.
siblings	number	1	Pages shown on each side of the current page in the numbered layout.
size	'lg' | 'xs' | 'sm' | 'md' | 'xl'		Size of every button, from the sizes config.
summaryLabel	(page: number, count: number) => string	config.labels.pageSummary	Text shown in the compact layout. Receives page 0 when there are no pages.
variant	Variantconfig	config.defaults.softVariant	Variant of the other pages and the previous and next buttons, from this component's variant map or shared variants.