Components

Pagination control

Provides controls for navigating backward and forward through content distributed across multiple pages

Overview

  • Available sinceQuebec
  • A11Y WCAG 2.1 AA

Pagination control divides a large set of content into multiple pages. It allows users move to the next or previous page, jump to specific pages across multiple pages.

ServiceNow link
Pagination control code documentation

UIB and developer guidance

Figma link
Pagination control Figma component

Figma library with components for designing Workspace.

Loading playground

When to use

Use pagination control when dealing with large datasets or lists of items that need to be organized across multiple pages. This helps users navigate through content without overwhelming them with excessive information on a single page.

When not to use

Don’t use pagination control when the content is manageable within a single view. Overusing pagination for minimal content can lead to unnecessary clicks and disrupt the user experience. Consider other functionalities such as infinite scrolling for a more streamlined experience.

Anatomy

anatomy of the pagination control component
  1. Page counter: Text noting current set of page numbers displayed in the total range
  2. First page arrow: Icon that navigates to the first page number in the range
  3. Previous page arrow: Icon that navigates to the previous page number in the range
  4. Page number range: Consecutively numbered pages in the range; the range changes as the number of records per page changes
  5. Next page arrow: Icon that navigates to the next page number in the range
  6. Last page arrow: Icon that navigates to the last page number in the range
  7. Dropdown: Dropdown that lets the user select the number of records to display on each page in the range

Subcomponents

See usage guidance for dropdown

See usage guidance for button iconic

Usage

Pagination control divides a large set of content into consolidated pages that the user can navigate.

Detailed list

Use the full pagination control with a list to help users navigate between pages.

detailed list with a full pagination control

In this example, pagination control appears underneath a list in a full-page display.

Simple list

You can also use pagination control in a simple list.

simple list with single page numbers and left and right arrows in pagination control

In this example, pagination control appears beneath a simple list to help the user navigate through service issues.

Configurations

Learn how to customize pagination control by configuring the available properties.

Presets and controllers

This component contains a preset configuration that automatically configures properties and event handlers for a component, making the component ready to work when you add it to a page. A preset is designed to suit a specific use case. However, you can override preset property values with a custom configuration if you find it necessary for your design. Preset values that you override aren’t upgraded when updates are available. If you don’t want to use the preset values provided, select the option to configure the component manually. You can apply one preset to a single instance of a component on a page. For more information, see Presets.

A preset is always associated with a controller, which acts as a data resource for the component. Controllers provide the configuration data and event bindings the component needs to function in your experience. By selecting a preset, the required controller is added to the page. By adding a controller to the page, any new applicable components will have that controller's preset. For more information about how controllers work, see Controllers. For instructions on using the data inspector to view the default presets for a component, see View properties and events in the Controller API.

Presets

This component contains preset configuration values that are intended for use with the record list component only. Some preset values for pagination control won’t function as expected if used with the standalone component. When using this component outside of the record list, select None for a preset and configure the component manually.

Shows the preset selection panel with None selected

This example shows the preset selection panel for pagination control. Designers should select None and configure the standalone component manually.

Display controls

You can configure pagination control to show or hide any of its subcomponents or elements. Your choices are based on the use case and space available.

pagination control with page counter, page number, and left and right arrows

In this example, pagination control displays only the page counter and the page numbers with arrows for a smaller set of data.

When the use case doesn’t specify a page counter, you can display a simplified pagination control with arrows for navigation to a set of previous or next pages.

pagination showing left and right arrows only

When pagination control is displayed as part of a list page, and the user groups records, you can configure the dropdown label with text that describes the rows per group instead.

pagination control with dropdown citing groups

In this example, customizable text for the page counter reads “Showing 1-20 of 100” and the dropdown label reads “Rows per group.”

Behavior

Learn how pagination control behaves when the display changes or a user interacts with the component.

States

Pagination control has the following states: default, hover, active, focus, and selected. For details about the dropdown states, see the usage guidelines.

State Example
Default now-pagination-control
Hover now-pagination-control
Active now-pagination-control
Focus now-pagination-control
Selected now-pagination-control

Responsive behaviors

Learn how pagination control responds to changes in a container or display.

Sizing

When pagination control is resized from a larger to a smaller display, the space between the page counter and page numbers decreases, as does the space between the dropdown and page numbers.

full pagination control with 10 page numbers

For smaller spaces, pagination control only shows the active page in addition to the first, previous, next, and last arrows.

pagination with left and right arrows and a single page number

Pagination control inherits the width of its container. The width of each page number expands to accommodate the full value (up to the ten-thousands).

page numbers in a container shown in the ten-thousands

Interactions

Learn how pagination control responds when a user interacts with it.

Page number shifting

If there are 10 pages visible in a larger range, all 10 pages remain visible until the user selects page number 7. The page numbers then shift by one page to the left. This pattern continues as the user selects subsequent page numbers.

pagination control with page 6 selected among 10 page numbers

When a page number shifts to the left or right, the selected page number remains in the center of the page range. If the last page shown in the visible range is selected, that number shifts to the center.

pagination control with page 7 selected among 10 page numbers

Users open the dropdown to configure the number of records per page for their list. The default number of records is 10.

Shows user interaction with the dropdown for selecting the number of records per page

When the user changes the number of records on the page, the page range scale adjusts to the change in the number of total pages. As the number of records per page increases, the number of pages decreases.

Shows how the number of pages displayed decreases as the user increases the number of records per page

Usability

Pagination control complies with all internationalization and accessibility requirements.

Internationalization

When the display translates to a right-to-left (RTL) language, the page order flips. The page counter and the dropdown also flip their orientation.

full pagination control showing translation for a right-to-left language

Accessibility

Learn how to access the actionable elements of pagination control through keyboard interactions and screen readers.

Keyboard interactions

You can access the actionable elements of pagination control with these keyboard keys:

  • Tab: Moves focus to the first interactive element and then through the page range in the tab order shown; the tab skips page arrows that are disabled because of the current page location
  • Tab + Shift: Moves focus to the previous interactive element; if no element is present, focus moves back to the element before pagination
  • Enter: Selects an action, such as a navigation arrow or page number.
    When focus is in the records per page control:
  • Enter: Opens the dropdown list
  • Arrow up or Arrow down: Moves focus up or down in the dropdown list of available row counts
    When focus is on a value in the dropdown list:
  • Enter: Selects the row count for the list

Screen readers

When you apply ARIA labels to a component, screen readers announce the controls and content of pagination control in the prescribed tab order.

  • Use aria-label to identify the navigation region
  • Assign role navigation to the pagination control
  • Ensure the current page has aria-current set to “true”
  • Use aria-disabled if a page link is disabled