Navigation
Pagination
Pagination lets users navigate through multiple pages.
Anatomy
The pagination contains 3 required elements and 5 optional elements.
| Item | Name | Description | Component | Optional |
|---|
Options
The pagination has options that can be used to provide an appropriate experience for different use cases.
First and last pagination item
Links to the first and last item.
Truncation
Truncation can be applied when there are more items than the width allows. Ellipsis are used to indicate additional items. Double truncation is applied when the current item is separated from both the first and last item.
Siblings
The main pagination items.
Boundaries
Pagination items to the left and right of the siblings.
Size
There are three sizes of pagination: small, medium, and large. The default is medium.
First and last pagination item
Links to the first and last item.
Truncation
Truncation can be applied when there are more items than the width allows. Ellipsis are used to indicate additional items. Double truncation is applied when the current item is separated from both the first and last item.
Siblings
The main pagination items.
Boundaries
Pagination items to the left and right of the siblings.
Size
There are three sizes of pagination: small, medium, and large. The default is medium.
States
Pagination has the following states:
Base
The default style before the user interacts with the pagination.
Focus
Communicates that a user has highlighted a pagination item (e.g. via keyboard or voice).
Hover
The pagination item changes style to let the user know it’s interactive.
Active
The pagination item changes style to provide feedback to the user that it has been interacted with.
Selected
The pagination item changes style to let the user know it is the current item that has been selected.
Disabled
Communicates that a pagination item exists, but isn’t available in that scenario. Applies when the user has reached the first or last pagination item.
Usage
The following guidance describes how and when to appropriately use the pagination component.
Use pagination when there are more than 25 results
This helps reduce cognitive load as the user is not overwhelmed with information.
Don’t split pagination over multiple lines
This can make pagination difficult for users to understand.
Do position pagination in a consistent place on each page
Pagination should appear in close proximity to the content, typically beneath the search results or listing.
Accessibility considerations
The Pagination has the following accessibility considerations:
Pagination is structured using an unordered list. The nav element is labeled ‘pagination’, making it a navigation landmark so that it is easy to locate using assistive tools.
| Order | Element | Role |
|---|
| Command | Description |
|---|
| Element | Attribute | Value | Description | User supplied |
|---|
API
The Pagination container component holds React content for its children
| Name | Type | Default | Description | Required |
|---|
From the Pagination props, it is possible to derive lastPage and selected props. This is something we do in the PaginationProviderContext that child components of Pagination can access. See Storybook examples for how to use the usePaginationContext hook in your custom components.
For reference, these are all the values it returns. In practice, you would only need a few of them:const { size, changePage, page, lastPage, pageSize, totalItems, buildHref } = usePaginationContext();
Most of these properties are also passed, for convenience, in the itemButton and itemDescription overrides that PaginationItems supports (to avoid the need to call the hook).
If writing a custom input component, lastPage can be used to validate that an input page number is within a valid range and selected can be used to just override the selected item button.
The PaginationItems child component shows pagination item links with numbers. Override icon if you want to change the appearance of the truncation icon. Override itemButton/itemDescription if you want to change/extend the appearance of the generated buttons.
| Name | Type | Default | Description | Required |
|---|
The PaginationItemFirst, PaginationItemPrev, PaginationItemNext and PaginationItemLast child components all take no props and the same set of overrides. Override icon if you want to change the appearance of the navigation icon. The defaults for paginationfirstItem, paginationPrevItem, paginationNextItem and paginationLastItem all reference the paginationItem stylePreset.
| Name | Type | Default | Description | Required |
|---|
The PaginationListItem is a styled LI element that should be used inside any custom Pagination components you write.
| Name | Type | Default | Description | Required |
|---|
The PaginationButton is default item button implementation. It is based on the Button component, as that supports a lot of styling options. These props do not need to be supplied manually, they will be provided in the props of the itemButton function. Overrides passed into PaginationItems get turned into standard Button props before being passed into this component.
| Name | Type | Default | Description | Required |
|---|
Default overrides used by the truncation icon.
| Attribute | Type | Default | Description |
|---|
Default overrides used by the TextBlock-based itemDescription override in PaginationItems. It uses utilityBody instead of utilityButton fonts, to match the lighter weight of text inside input/dropdown custom components.
| Attribute | Type | Default | Description |
|---|