Anatomy
Note: Image not to scale
- Page navigation button
- Unselected page button
- Selected/current page button
- Page overflow button
- Page indicator
- Item range indicator*
*Item range indicator is especially valuable in data-heavy interfaces where users need to navigate through large sets of information efficiently. It may be omitted where space is limited or such precise context isn't necessary.
Note: The page navigation and unselected page buttons use the secondary variant of the button component. The selected (also known as current) page button uses the secondary variant with disabled state styles, but with onSecondary color token and bold font for the text instead.
Options
Numeric display
The numeric display option renders page numbers as interactive, clickable buttons in a familiar sequential format, allowing users to quickly jump to specific pages.
Descriptive display
For situations requiring more explicit navigation context, the descriptive display option presents the current position using a textual format, which enhances clarity and accessibility.
Compact display
When space efficiency is paramount, the compact display option implements a streamlined fraction-style presentation, efficiently communicating position while minimizing interface real estate.
No display
The no display option eliminates visual page indicators entirely while preserving essential navigation functionality, and is ideal for minimalist designs.
Behavior
Triggers
- When clicking the next or previous page buttons, the page numbers update and content transitions smoothly.
- When clicking on the fifth page from the first and the last pages, it’s selected state will appear as the middle page number, and the overflow buttons appear.
- The overflow button triggers the next set of sequential numbers, allowing users to jump three pages.
Guidance
Endless pagination
Endless pagination, also known as infinite scroll, should be reserved for content-heavy scenarios like article feeds or large datasets, as implementing it for standard navigation can lead to poor user orientation, difficulty in reaching specific pages, and potential performance issues. Including the first page in the numeric display variant can help users return quickly to the beginning of their content journey without having to navigate through multiple steps.
Mobile and smaller screens
Implement a responsive pagination component with a mobile-optimized fallback variant. The component should dynamically switch to a compact UI based on viewport dimensions or container constraints, ensuring consistent UX while maintaining core navigation features across all device sizes.
Accessibility
Keyboard controls
API Reference
Pagination
| Prop | Description | Type | Default | Required |
|---|
PaginationRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| page | The current page | number | ---- | True |
| showItems | Whether to show item range indicator | boolean & (boolean | "true" | ({ "@notSm"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; ... 18 more ...; "@initial"?: boolean | "true"; } & { ...; })) | ---- | True |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; } | ---- | False |
| endlessPagination | Whether or not endless pagination | boolean | ---- | True |
| setPage | Function to change current page | Dispatch<SetStateAction<number>> | ---- | True |
| slug | Current page slug | string | ---- | True |
| totalPages | Total number of pages to display | number | ---- | True |
| variant | Component variant | string | ---- | True |
PaginationDisplay
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
PaginationItemRangeIndicator
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| items | Number of results | number | ---- | True |
| showTotal | Whether to show total variation in item range indicator | boolean | ---- | True |
PaginationPreviousButton
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| icon | "left" | "right" | "center" | "none" | ({ "@notSm"?: "left" | "right" | "center" | "none"; "@sm"?: "left" | "right" | "center" | "none"; "@md"?: "left" | "right" | "center" | "none"; "@lg"?: "left" | ... 2 more ... | "none"; ... 20 more ...; "@initial"?: "left" | ... 2 more ... | "none"; } & { ...; }) | left | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
| variant | "cta" | "secondary" | "primary" | ({ "@notSm"?: "cta" | "secondary" | "primary"; "@sm"?: "cta" | "secondary" | "primary"; "@md"?: "cta" | "secondary" | "primary"; "@lg"?: "cta" | "secondary" | "primary"; ... 20 more ...; "@initial"?: "cta" | ... 1 more ... | "primary"; } & { ...; }) | ---- | False | |
| density | "default" | "compact" | ({ "@notSm"?: "default" | "compact"; "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; "@xxl"?: "default" | "compact"; ... 18 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | compact | False | |
| isOutline | boolean | "true" | "false" | ({ "@notSm"?: boolean | "true" | "false"; "@sm"?: boolean | "true" | "false"; "@md"?: boolean | "true" | "false"; "@lg"?: boolean | "true" | "false"; "@xl"?: boolean | "true" | "false"; ... 19 more ...; "@initial"?: boolean | ... 1 more ... | "false"; } & { ...; }) | ---- | False |
PaginationNextButton
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| icon | "left" | "right" | "center" | "none" | ({ "@notSm"?: "left" | "right" | "center" | "none"; "@sm"?: "left" | "right" | "center" | "none"; "@md"?: "left" | "right" | "center" | "none"; "@lg"?: "left" | ... 2 more ... | "none"; ... 20 more ...; "@initial"?: "left" | ... 2 more ... | "none"; } & { ...; }) | right | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS... | ---- | False |
| variant | "cta" | "secondary" | "primary" | ({ "@notSm"?: "cta" | "secondary" | "primary"; "@sm"?: "cta" | "secondary" | "primary"; "@md"?: "cta" | "secondary" | "primary"; "@lg"?: "cta" | "secondary" | "primary"; ... 20 more ...; "@initial"?: "cta" | ... 1 more ... | "primary"; } & { ...; }) | ---- | False | |
| density | "default" | "compact" | ({ "@notSm"?: "default" | "compact"; "@sm"?: "default" | "compact"; "@md"?: "default" | "compact"; "@lg"?: "default" | "compact"; "@xl"?: "default" | "compact"; "@xxl"?: "default" | "compact"; ... 18 more ...; "@initial"?: "default" | "compact"; } & { ...; }) | compact | False | |
| isOutline | boolean | "true" | "false" | ({ "@notSm"?: boolean | "true" | "false"; "@sm"?: boolean | "true" | "false"; "@md"?: boolean | "true" | "false"; "@lg"?: boolean | "true" | "false"; "@xl"?: boolean | "true" | "false"; ... 19 more ...; "@initial"?: boolean | ... 1 more ... | "false"; } & { ...; }) | ---- | False |