Newskit Logo

Getting started

Design overview

Popular searches

View GitHub

Navigation

Pagination

Pagination lets users navigate through multiple pages.

Status

Supported

Introduced

v7.1.0
View StorybookView Design

Anatomy

The pagination contains 3 required elements and 5 optional elements.

ItemNameDescriptionComponentOptional

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.

Focus order
OrderElementRole
Keyboard interactions
CommandDescription
WAI-ARIA
ElementAttributeValueDescriptionUser supplied

API

Pagination

The Pagination container component holds React content for its children

NameTypeDefaultDescriptionRequired

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.

Pagination items

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.

NameTypeDefaultDescriptionRequired
Pagination navigation items

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.

NameTypeDefaultDescriptionRequired
Pagination list item

The PaginationListItem is a styled LI element that should be used inside any custom Pagination components you write.

NameTypeDefaultDescriptionRequired
Pagination button

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.

NameTypeDefaultDescriptionRequired
Truncation icon defaults

Default overrides used by the truncation icon.

AttributeTypeDefaultDescription
Pagination item description defaults

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.

AttributeTypeDefaultDescription

Need Help?

Cant find what you are looking for?

Get In Touch

Need Help?

Cant find what you are looking for?