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}' * @showInPropTable*/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 | 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 | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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 | |
hrefTemplate | undefined | string | - | - | 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 | 'Pagination' | - | The label of the Pagination component |
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 | undefined | React.ComponentType<any> | - | - | Custom router component to use for client-side navigation Custom router component to use for client-side navigation when hrefTemplate is provided |
variant | "extended" | "minimal" | 'extended' | - | The visual variant of the Pagination component |
PageSize Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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. |
maxListHeight | string | number | '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[] | '[10, 15, 20]' | - | Page size options to display in the dropdown |
setPageSize | React.Dispatch<React.SetStateAction<number>> | - | Callback function executed when the selected page size changes |
Below are the link(s) to the relevant GitHub type files:
RowCount Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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. |
rowCount | number | - | The number of rows in the current page |
Below are the link(s) to the relevant GitHub type files:
Results Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
additionalText | string | - | - | Additional text to display below the results |
ariaLiveActive | boolean | true | - | If true, the results will be announced by screen readers whenever the component is updated |
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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. |
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 |
Below are the link(s) to the relevant GitHub type files:
Pagination Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-ellipsis | Pagination ellipsis |
| .abyss-pagination-button-container | Container for pagination buttons |
| .abyss-pagination-page-button | Pagination page Button |
| .abyss-pagination-link-container | Container for pagination links |
| .abyss-pagination-page-link | Pagination link |
| .abyss-pagination-abbreviated-container | Pagination abbreviated container |
| .abyss-pagination-root-container | Root container for pagination |
| .abyss-pagination-root | Root element for pagination |
| .abyss-pagination-arrow | Pagination arrow icon container |
| .abyss-pagination-icon | Pagination arrow icon |
| .abyss-pagination-text | Pagination button text |
| .abyss-pagination-icon-left | Pagination left arrow icon |
| .abyss-pagination-text-left | Pagination previous button text |
| .abyss-pagination-text-right | Pagination next button text |
| .abyss-pagination-icon-right | Pagination right arrow icon |
PageSize Classes
| Class Name | Description |
|---|---|
| .abyss-pagination-page-size-root | Page size root element |
| .abyss-pagination-page-size-select-input | Page size select element |
| .abyss-pagination-page-size-label | Page size label 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) - tempertemper
- Should pagination take you to a new page? - tempertemper
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
Note: 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 |