page | number · requiredCurrent page number (1-based). Page 1 is the first page. |
|---|
onChange | (page: number) => void · requiredCalled when the page changes. |
|---|
changeAction | (page: number) => void | Promise<void>Async action on page change. Fires after onChange and uses React transitions for built-in loading state. |
|---|
totalItems | numberTotal number of items. Used to calculate page count. Takes precedence over totalPages if both provided. |
|---|
totalPages | numberTotal number of pages. Use when you know page count but not item count. |
|---|
hasMore | booleanWhether more pages exist after the current one. Use for cursor-based pagination where total is unknown. |
|---|
pageSize | number · default 10Number of items per page. Coerced to a positive integer; non-finite values fall back to the default. |
|---|
pageSizeOptions | number[]Available page size options. Shows a page size selector dropdown when provided. |
|---|
onPageSizeChange | (pageSize: number) => voidCalled when the page size changes. Automatically resets to page 1. |
|---|
variant | 'pages' | 'count' | 'compact' | 'dots' | 'input' | 'none' · default 'pages'Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'input' shows an editable page-number box with a leading label ('Page [ n ] / N') flanked by first/last buttons by default (the box needs a known total to clamp against, so it is disabled in cursor/hasMore mode), 'none' shows just prev/next buttons. |
|---|
pageLabel | stringThe noun rendered before the editable box in the 'input' variant, e.g. 'Page' or 'Row'. Navigation is always page-based (via onChange); this only relabels the box. Defaults to the localized 'Page'. |
|---|
hasFirstLast | boolean · default trueWhether to show first/last («/») double-chevron buttons flanking prev/next. Only applies to the 'input' variant; omitted when the page count is unknown (cursor/hasMore pagination). |
|---|
step | number · default 1Number of pages the previous/next buttons advance per click. Clamped to the valid page range, so a step that would overshoot lands on the first/last page. When greater than 1, the buttons' accessible names reflect the stride. Non-integer or values < 1 fall back to 1. |
|---|
siblingCount | number · default 1Number of page buttons to show on each side of the current page. Only applies when variant='pages'. |
|---|
size | 'sm' | 'md' · default 'md'Size of the pagination controls. |
|---|
isDisabled | boolean · default falseWhether the component is disabled. |
|---|
label | string · default 'Pagination'Accessible label for the navigation landmark. |
|---|
xstyle | StyleXStylesStyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |
|---|