import { Pagination } from '@uhg-abyss/web/ui/Pagination';Pagination
Use the pages parameter in the usePagination hook to set the number of pages to display.
Examples of Pagination being used can be seen in DataTable.
Variants
Use the variant prop to change the format of the pagination display. Possible options are minimal and extended, and the default value is extended.
PageSize
import { PageSize } from '@uhg-abyss/web/ui/Pagination';The PageSize component is used to change how many rows to display per page. For an example of its usage, see the DataTable docs.
Its props are:
pageSizeOptions: The possible values for the dropdown. The default value is[10, 15, 20].pageSize: The current selected value from thepageSizeOptions. This prop is required.setPageSize: Function to set the current value of thepageSizeprop. This prop is required.maxListHeight: Controls the maximum height of the dropdown list. Increase this value to show more options without a scrollbar. The default value is'115px'.
Results
import { Results } from '@uhg-abyss/web/ui/Pagination';The Results component can display information about the data being displayed. For an example of its usage, see the DataTable docs.
Its props are:
pageIndex: The current page index in the pagination. This prop is required.pageSize: The current size per page. This prop is required.resultsTotalCount: The total number of rows in data set. This prop is required.
Additional text
Use the additionalText prop to display additional information underneath the text.
RowCount
import { RowCount } from '@uhg-abyss/web/ui/Pagination';The RowCount component displays how many rows are currently on the page. For an example of its usage, see the DataTable docs.
Its props are:
rowCount: The number of rows currently being displayed to the user. This prop is required.
Pagination use cases
Updates part of page
The Pagination component is used to navigate between pages of data.
The most common use case is when the pagination is used to update a portion of the page, such as a table. For example, we use it within the DataTable component. All of the examples on this page demonstrate this use case.
Full page navigation
The Pagination component can also be used to navigate between full pages of content. To achieve this functionality, the buttons for navigation are instead rendered as links, which means an href also needs to be provided.
Use the hrefTemplate prop to provide a template for the href that can be reused for each page link.
/** * URL template for generating page links. * Using this prop renders page buttons as links for full page navigation. * Use {page} as placeholder for the 1-indexed page number. * @example '/search/page/{page}'*/hrefTemplate?: string;To keep the Pagination component up to date after navigation to a new page, you will need to use the usePagination hook and its goToPage method to update the currentPage prop accordingly.
Pagination Props
| Name | Type | Default | Required | A11y | Description |
|---|---|---|---|---|---|
canNextPage | boolean | If true, there is a page after the current page | |||
canPreviousPage | boolean | If true, there is a page before the current page | |||
className | string | undefined | CSS class name to apply to each element within the component | |||
css | CSSProperties | Partial<Record<"abyss-pagination-root" | "abyss-pagination-text" | "abyss-pagination-icon" | "abyss-pagination-root-container" | "abyss-pagination-page-button" | ... 9 more ... | "abyss-pagination-icon-right", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | |||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | |||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | ||
goToPage | (pageNumber: number) => void | Function to navigate to a specific page | |||
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | |||
hrefTemplate | string | undefined | URL template for generating page links. Using this prop renders page buttons as links for full page navigation. Use {page} as placeholder for the 1-indexed page number. | |||
label | string | undefined | 'Pagination' | The accessible name for the pagination <nav> landmark, exposed to screen readers via aria-label. | ||
nextPage | () => void | Function to navigate to the next page | |||
pageCount | number | The total number of pages | |||
pageIndex | number | 0-based index of the current page | |||
previousPage | () => void | Function to navigate to the previous page | |||
routerComponent | ComponentType<any> | undefined | Custom router component to use for client-side navigation when hrefTemplate is provided Custom router component to use for client-side navigation | |||
slotProps | Partial<Record<ToSlotKey<{ root: LeafSlotDef<"ul", undefined>; rootContainer: LeafSlotDef<"nav", undefined>; abbreviatedContainer: LeafSlotDef<"li", undefined>; ... 11 more ...; iconRight: LeafSlotDef<...>; }, "pagination">, SlotPropsLeafValue>> | undefined | Props to pass to individual internal slots of the component. To target slots inside sub-components, nest the sub-component's slotProps under the parent slot key: slotProps={{ '<component>-<sub>': { slotProps: { '<inner-key>': {...} } } }} See slotProps for more information | |||
variant | "minimal" | "extended" | undefined | 'extended' | The visual variant of the Pagination component | ||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
PageSize Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | undefined | CSS class name to apply to each element within the component | ||
css | CSSProperties | Partial<Record<"abyss-pagination-page-size-label" | "abyss-pagination-page-size-root" | "abyss-pagination-page-size-select-input", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | ||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | ||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | |
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | ||
maxListHeight | string | number | undefined | '115px' | Maximum height for the page size dropdown list. | |
pageSize | number | The currently selected page size option. Must be a value present in pageSizeOptions. | ||
pageSizeOptions | number[] | undefined | [10, 15, 20] | Page size options to display in the dropdown | |
setPageSize | (value: SetStateAction<number>) => void | Callback function executed when the selected page size changes | ||
slotProps | Partial<Record<string, SlotPropsValue<string>>> | undefined | Props to pass to individual internal slots of the component, keyed by the slot name (e.g. 'button-root'). Supports className, css, style, aria-*, data-*, data-testid, and nested slotProps for child Abyss components. See slotProps for more information | ||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
RowCount Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | undefined | CSS class name to apply to each element within the component | ||
css | CSSProperties | Partial<Record<"abyss-pagination-row-count-text" | "abyss-pagination-row-count-root", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | ||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | ||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | |
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | ||
rowCount | number | The number of rows in the current page | ||
slotProps | Partial<Record<string, SlotPropsValue<string>>> | undefined | Props to pass to individual internal slots of the component, keyed by the slot name (e.g. 'button-root'). Supports className, css, style, aria-*, data-*, data-testid, and nested slotProps for child Abyss components. See slotProps for more information | ||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
Results Props
| Name | Type | Default | Required | A11y | Description |
|---|---|---|---|---|---|
additionalText | string | undefined | Additional text to display below the results | |||
ariaLiveActive | boolean | undefined | true | If true, the results will be announced by screen readers whenever the component is updated | ||
className | string | undefined | CSS class name to apply to each element within the component | |||
css | CSSProperties | Partial<Record<"abyss-pagination-results-text" | "abyss-pagination-results-root", CSSProperties>> | undefined | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information | |||
data-testid | string | undefined | Suffix used to create a unique ID used for automated testing See Component Testing for more information | |||
disableDefaultProviderProps | boolean | undefined | false | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. | ||
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | |||
pageIndex | number | 0-based index of the current page | |||
pageSize | number | The number of items to display on each page | |||
resultsTotalCount | number | The total number of items in the data set | |||
slotProps | Partial<Record<string, SlotPropsValue<string>>> | undefined | Props to pass to individual internal slots of the component, keyed by the slot name (e.g. 'button-root'). Supports className, css, style, aria-*, data-*, data-testid, and nested slotProps for child Abyss components. See slotProps for more information | |||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
Pagination Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-abbreviated-container | Pagination abbreviated container |
| .abyss-pagination-arrow | Pagination arrow icon container |
| .abyss-pagination-button-container | Container for pagination buttons |
| .abyss-pagination-ellipsis | Pagination ellipsis |
| .abyss-pagination-icon | Pagination icon |
| .abyss-pagination-icon-left | Pagination left arrow icon |
| .abyss-pagination-icon-right | Pagination right arrow icon |
| .abyss-pagination-link-container | Container for pagination links |
| .abyss-pagination-page-button | Pagination page button |
| .abyss-pagination-page-link | Pagination page link |
| .abyss-pagination-root | Pagination root element |
| .abyss-pagination-root-container | Root container for pagination |
| .abyss-pagination-text | Pagination button text |
| .abyss-pagination-text-left | Pagination previous button text |
| .abyss-pagination-text-right | Pagination next button text |
PageSize Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-page-size-label | Page size label element |
| .abyss-pagination-page-size-root | Page size root element |
| .abyss-pagination-page-size-select-input | Page size select element |
RowCount Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-row-count-root | Row count root element |
| .abyss-pagination-row-count-text | Row count text element |
Results Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-results-root | Pagination results root element |
| .abyss-pagination-results-text | Pagination results additional text |
The pagination root container(nav) must have a descriptive accessible name. For example, if the pagination control is used for a table, the accessible name might be "table" pagination. If the pagination control is used for search results, the accessible name might be "search results" pagination.
Should navigation take you to a new page?
We allow two patterns for navigation:
- In-page navigation - The pagination updates a portion of the page (e.g., a table or list of results)
- Full page navigation - The pagination navigates to a new page (e.g., a search results page) with the use of prop
hrefTemplate
Further reading:
- An accessible pagination pattern (or two) - tempertemperopens in a new window
- Should pagination take you to a new page? - tempertemperopens in a new window
Accepted BrAT Variant Behaviors
- ALL (JAWS, NVDA, VoiceOver)
- Announce status update "X of Y" when changing pages
- "X of Y" announced in normal reading order between [ < ] and [ > ]
- JAWS
- Correctly announces "list of 2 items"
- Does not announce "X of Y" as part of
<nav>on focus
- NVDA, VoiceOver (Mac)
- Incorrectly announces "list of 3 items"
- Does announce "X of Y" as part of
<nav>on focus
Component Tokens
Tip
Click on the token row to copy the token to your clipboard.
Pagination Tokens
| Token Name | Value | |
|---|---|---|
| pagination.color.icon.dropdown-menu.rest | #4B4D4F | |
| pagination.color.icon.dropdown-menu.hover | #323334 | |
| pagination.color.icon.dropdown-menu.active | #000000 | |
| pagination.color.icon.navigation.rest | #196ECF | |
| pagination.color.icon.navigation.active | #002677 | |
| pagination.color.icon.navigation.hover | #004BA0 | |
| pagination.color.icon.navigation.disabled | #7D7F81 | |
| pagination.color.border.dropdown-menu | #CBCCCD | |
| pagination.color.surface.digits.rest | #FFFFFF | |
| pagination.color.surface.digits.hover | #F3F3F3 | |
| pagination.color.surface.digits.active | #E5E5E6 | |
| pagination.color.surface.digits.selected | #FFFFFF | |
| pagination.color.surface.dropdown-menu | #FFFFFF | |
| pagination.color.surface.page-button.rest | #FFFFFF | |
| pagination.color.surface.page-button.active | #E5E5E6 | |
| pagination.color.surface.page-button.hover | #F3F3F3 | |
| pagination.color.surface.page-button.selected | #002677 | |
| pagination.color.text.label.digits | #4B4D4F | |
| pagination.color.text.label.dropdown-menu | #4B4D4F | |
| pagination.color.text.label.page-button.rest | #4B4D4F | |
| pagination.color.text.label.page-button.active | #4B4D4F | |
| pagination.color.text.label.page-button.selected | #FFFFFF | |
| pagination.color.text.label.page-button.hover | #4B4D4F | |
| pagination.color.text.label.navigation.rest | #196ECF | |
| pagination.color.text.label.navigation.active | #002677 | |
| pagination.color.text.label.navigation.hover | #004BA0 | |
| pagination.color.text.label.navigation.disabled | #7D7F81 | |
| pagination.color.text.label.pages | #4B4D4F | |
| pagination.color.text.label.results | #4B4D4F | |
| pagination.border-radius.all.dropdown-menu | 4px | |
| pagination.border-radius.all.page-button | 500px | |
| pagination.border-width.all.dropdown-menu | 1px | |
| pagination.sizing.all.icon.dropdown | 24px | |
| pagination.sizing.all.icon.navigation | 24px | |
| pagination.spacing.gap.horizontal.container | 24px | |
| pagination.spacing.gap.horizontal.minimal | 4px | |
| pagination.spacing.gap.horizontal.page-button | 8px | |
| pagination.spacing.gap.horizontal.results | 4px | |
| pagination.spacing.gap.vertical.dropdown | 4px | |
| pagination.spacing.padding.all.dropdown-digit | 8px | |
| pagination.spacing.padding.bottom.dropdown | 2px |