Skip to main content

Table pagination

Table pagination in Storybook

Usage​

Overview​

Pagination enables users to navigate large datasets by dividing content into manageable pages. It provides controls to browse through pages and adjust the number of items displayed at one time, which is essential for maintaining performance and readability in data-heavy applications.

When to use​

  • To manage large datasets: Use when a table has hundreds or thousands of rows, and rendering them all at once impacts performance or page loading times.
  • To improve scannability: Use when too much data on one page overwhelms users, making it harder to find or compare values.
  • To enhance accessibility: Use when large tables create navigation issues for screen readers or keyboard users (for example, a table with hundreds of rows is impractical to explore).
  • For filtered views: Use when users typically view a subset of data, like search results or filtered views. Pagination keeps them oriented and helps with manageable chunks.

When not to use​

  • For small datasets: Avoid if all rows can be displayed without performance issues or overwhelming the user (for example, 20-50 rows).
  • For broad comparison tasks: Avoid when users need to compare many rows at once; consider virtual scrolling or filtered views instead.
  • For single-view tasks: Don't use if the dataset represents a complete set that cannot be split across pages, like a settings table.

Formatting​

Anatomy​

Anatomy of the pagination component, with numbered callouts for the "Rows per page" selector, item range display, and navigation buttons.

The pagination component appears at the bottom of the content it controls and consists of the following elements:

  1. Rows per page select: A dropdown that allows users to change the number of items displayed on each page.
  2. Item range display: A text label that communicates which items are currently being viewed in the context of the total number of items (for example, "1 - 10 of 25").
  3. Navigation controls: Icon buttons that enable users to move to the previous or next page of data, as well as navigate to the first and last page.

Content​

General writing guidelines​

  • Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
  • Use present tense verbs and active voice in most situations.
  • Use common contractions to lend your copy a more natural and informal tone.
  • Use plain language. Avoid unnecessary jargon and complex language.
  • Keep words and sentences short.

Behaviors​

States​

The primary states of the pagination component relate to its navigation controls.

  • The Previous page button must be disabled when the user is on the first page of data.
  • The Next page button must be disabled when the user is on the last page of data.

Interactions​

  • Selecting a new value from the Rows per page dropdown reloads the associated component to display the chosen number of items.
  • Clicking the Next page or Previous page buttons navigates the user through the dataset one page at a time.

Pagination usage approaches​

  • Default usage: Use the component in a standard, synchronous context. Customers provide the values directly to the component.
  • Async table usage: When used with tables that fetch data asynchronously from a server, pagination reflects the table's current state. The component itself remains synchronous; the table manages async logic. This approach is applicable to both the default usage and when using TanStack Table.
  • TanStack table usage: When using a table managed by TanStack Table, the consumer passes the table's pagination state to the pagination component. This allows the pagination UI to reflect the current table state, including any async or server-driven updates managed by the table.

Accessibility​

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

When using this component within your application, observe these best practices:

  • Keyboard interaction: All controls within the pagination component must be keyboard focusable and operable. Users must be able to navigate between the dropdown and the navigation buttons using the Tab key and activate them using the Enter or Space keys.
  • Screen reader: The pagination component must be wrapped in a <nav> element with an aria-label of "Pagination" to identify it as a landmark region. All controls must have clear, accessible names. For the navigation buttons, use aria-label attributes like "Go to previous page" and "Go to next page". The item range display (for example, "1 - 10 of 25") must be programmatically associated with the controls so it can be announced to screen reader users, providing essential context for navigation.