Examples

Guidance

Paginated content is any content split into multiple pages determined by a specific amount of content per page, not split by any meaningful attribute, like feature or subject or step. Search results and article collections are often paginated. Readers use the pagination component to move from page to page in paginated content, or directly to the first or last page of the paginated set.

When to use

• Typically used for paginated search results.
• Can be used for multi-page collections of related items, including articles related to a category or tag, content archives, and history or activity. Splitting a large collection of related items into individual pages can improve browsability and scannability.

When to consider alternatives

• If you need to indicate progress in a series of steps that must be completed in succession, like an onboarding or checkout flow, this isn't the component for you.
• If the length of the entire collection is less than 3-4 screen lengths long, consider showing all the items at once instead of paginating.

Usage

• Users want to know the length of a paginated section, so show the size of the paginated set.
• Highlight the current page the user is on in relation to the entire collection of pages.
• Don't split the navigation items over multiple lines as this can make individual pages more difficult to understand and select.
• Don't include out-of-sequence items directly adjacent to one another. Wherever there are missing pages, an ellipses should be used.
• Avoid adding complexity by focusing on the essentials and avoid adding more items to Pagination just to fill the space.
• Use touch targets that are big enough to select with any finger and have enough separation to avoid mistakes.
• Do not use buttons for URL-based pagination. Because the URL is updated, the browser history stack updates and a link is the correct tag to use.
• Consider page load, performance, and the user's scrolling preferences when determining how many items are displayed on each page.

Accessibility

The Pagination component has been tested against, and meets, WCAG 2.0 standards for text size, color contrast, and screenreader usage.

Accessibility Guidance

• The Pagination component uses a wrapping <nav> element to identify it as a navigation section to screen readers and other assistive technologies.
• Itʼs likely that you will have more than one <nav> on a page. If you do, Pagination must have an ARIA label attribute defined on the <nav> element that describes its purpose. To do this, supply a string value to the ariaLabel prop on the component adequately describing the purpose. “Pagination resultsˮ is a possible option.
• The component sets aria-current="page" on the <span> element containing the current page value to properly voice the current page for screen readers.
• The component adds an aria-label to the pagination item with the word “pageˮ and the page number so that screen readers will voice the word "page" before the page numbers automatically.
• Once a pagination link has been clicked, the user should be redirected to that content and focus should shift to the top-level piece of content on that page, usually an <h1>, but this depends on content being paginated over.
• Uses an <a> element for the non-current pages. They are announced consistently by screen readers, and function as anchor links do normally (i.e. interactive and link to content).
• Avoid large horizontal gaps between pagination elements, as this may cause users with limited vision or mobility to miss items when scanning. For mobile devices and devices with smaller screens we offer the compact boolean prop which changes the layout from using a series of anchor links for each page to instead rendering the text “Page X of Yˮ.

Accessibility Testing

Keyboard navigation

• If the "Previous" navigation link has keyboard focus, pressing the TAB key should move focus to the first pagination page link.
• If a pagination page link has keyboard focus, pressing TAB should move focus to the next pagination link in sequence.
• If the last pagination page link has keyboard focus, pressing TAB should move focus to the "Next" navigation link.
• The currently active page link should not receive keyboard focus when pressing TAB.
• Verify that keyboard focus is not trapped in the pagination and that users can tab into and out of the component.
• Confirm a visible focus indicator appears on each pagination link when using a keyboard.

Zoom magnification

• When zoomed to 200%, pagination content must remain legible, functional, and properly sized. The component should automatically adjust to mobile styling.

Screen reader

• Screen readers must announce pagination links in the correct visual and numerical order.
• Screen readers must announce the role and label of each link (e.g., 'link, page 10').

Code

React

Pagination requires three properties: totalPages, which is the total number of pages, currentPage, which acts a means to track the current page, and onPageChange, which is a function used to handle state changes when the user clicks a page.

Pagination also comes in two styles: default, which is compact on mobile viewports and expands to reveal individual pages on larger viewports, and compact, which maintains the compact layout regardless of viewport size.

Review Storybook for React guidance of this component.

Web Component

Go to Storybook for Web Component guidance of this component.

Style customization

The following CSS variables can be overridden to customize Pagination components:

Component maturity