Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

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 the pageSizeOptions. This prop is required.
• setPageSize: Function to set the current value of the pageSize prop. This prop is required.

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 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 See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
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
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
variant	"extended" | "minimal"	'extended'	-	The visual variant of the Pagination component

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Pagination.types.ts

usePagination.types.ts

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 See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
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.
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:

PageSize.types.ts

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 See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
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:

RowCount.types.ts

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 See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
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:

Results.types.ts

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-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.

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.

Search tokens

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