Pagination

Pagination divides a collection of data or other content types such as images, cards, or search results into multiple pages showing a fixed number of items per page.

Status

Figma UI Kit	PublishedElement can be used in production
Vanilla	PublishedElement can be used in production
Angular	In backlogElement is in backlog
React	In backlogElement is in backlog
Documentation	PublishedElement can be used in production

What's new

Pagination was previously named “Standard Pagination” and was featured in the “Pagination” section of DDS v1. This component has been redesigned to the updated font ramp and color palette, in addition to accessibility enhancements.

Anatomy

The pagination component is comprised of the following elements:

Capacity

Label per page: describes the content divided by page, such as rows, images, or results.
Capacity control: select component that allows the user to determine the number of items per page. The default values are 10, 25, 50, 100, and 250, but can be customized.
Range label: describes what range of items are in view up to the total.

Navigation
4. First page button: takes the user back to the first page.
5. Previous button: takes the user to the previous page.
6. Next button: takes the user to the next page.
7. Last page button: takes the user to the last page.
8. Location: text input showing what page the user is viewing, which can also be used for navigation.
9. Label of total pages: shows the number of pages based on the capacity of items per page.

Usage

Consider using the pagination component to make a large amount of related content more consumable to your users, or to optimize on-page real estate or load times in your experience. Pagination elements allow users to control how much information they’d like to see per page, and navigate all of the data or content types in a smaller, more controlled view. Controls are centered below the paginated items, whether it is on-page, below a table, or embedded in another component.

On-page

Pagination is typically not required when there are 25 or fewer items per page. Depending on the context, however, consider reducing the capacity of items per page. Considerations include smaller screen sizes or when other variables increase vertical scroll.

The “First page” and “Previous” buttons are inactive when users are on the first page. Likewise, the “Next” and “Last page” buttons are inactive when users are on the last page.

Embedded

Pagination can be used within components, such as tables, to help users navigate large data sets or other content.

Sizes

The following sizes are recommended for their respective pixel ranges. Layouts or viewport size can limit or reprioritize controls within the component.

Size	Use case
1024 or larger	For 1024 pixels and larger, the component contains all of the elements for the capacity and navigation features.
768 to 1023	Removes “Page label” from the navigation controls.
640 to 767	Removes all labels within the navigation feature. “Previous” and “Next” buttons become icon only.
480 to 639	Removes all labels within the navigation feature and no longer states the total number of pages within the component. Additionally removes the label items “per page” on the capacity controls and reduces the overall height of the component.
360 to 479	Includes only the preset interval select component within the capacity control. The navigation feature is reduced to “Previous” and “Next” icon-only buttons, and the current page input. The overall height of the component decreases further.
288 to 359	Includes navigation elements as icon-only buttons. “First page”, “Previous”, “Next”, and “Last page” are all featured, as well as the current page input. The label containing the total number of pages is also shown. Additionally, the overall height of the component decreases again.

Standards

Accessibility

Icon-only buttons should be used carefully and only after checking for accessibility
The meaning of the icon must be visually self-evident (easily and universally understood). In addition, a programmatically associated semantic label (such as an aria-label attribute) should be added so it can be read by screen readers. If you’re in any doubt that an icon-only button will be understood, use accompanying text in your button label.
WCAG 2.1: 1.3.1 Info and Relationships

All buttons except tertiary should have a contrast ratio of 3:1 or greater against the background, regardless of breakpoint or orientation (except if inactive)
Providing good contrast ratio on buttons ensures that anyone with low vision can see them and perceive their function. If the button variant doesn’t achieve adequate contrast with the background when viewed at a specific breakpoint, and/or in a particular orientation, either change the background or consider using a different button variant. The tertiary button is an exception and should have 4.5:1 contrast with its background at all times.
WCAG 2.1: 1.4.11 Non-text Contrast

Tertiary buttons require a 4.5:1 contrast ratio against the background
Greater contrast is required because the text is the only part of the button that is visible. These buttons are therefore considered similar to text and will require a higher contrast ratio.
WCAG 2.1: 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast

Live demo

This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.

You are now entering a live demo of the component.

<div class="dds__pagination" data-dds="pagination" id="590825466" role="navigation">
  <div class="dds__pagination__summary">
    <label class="dds__pagination__per-page-label" for="590825466-per-page">Items per page</label>
    <div class="dds__select dds__select--sm dds__pagination__per-page-select" data-dds="select">
      <div class="dds__select__wrapper">
        <select class="dds__select__field" id="590825466-per-page">
          <option value="10">10</option>
          <option value="20">20</option>
          <option value="30">30</option>
        </select>
      </div>
    </div>
    <div class="dds__pagination__range" aria-live="polite">
      <span class="dds__pagination__range-start"></span>
      -
      <span class="dds__pagination__range-end"></span>
      <span class="dds__pagination__range-total-label">
        of
        <span class="dds__pagination__range-total"></span>
        items
      </span>
    </div>
  </div>
  <div class="dds__pagination__nav">
    <button
      class="dds__button dds__button--tertiary dds__button--sm dds__button__icon dds__pagination__first-page"
      aria-label="First page"
    ></button>
    <button class="dds__button dds__button--tertiary dds__button--sm dds__pagination__prev-page" aria-label="Previous page">
      <span class="dds__pagination__prev-page-label">Previous</span>
    </button>
    <div class="dds__pagination__page-range">
      <label class="dds__pagination__page-range-label" for="590825466-current-page">Page</label>
      <div class="dds__input-text__container dds__input-text__container--sm">
        <div class="dds__input-text__wrapper dds__pagination__page-range-current-wrapper">
          <input class="dds__input-text dds__pagination__page-range-current" type="text" id="590825466-current-page" />
        </div>
      </div>
      <div class="dds__pagination__page-range-total-label">
        of
        <span class="dds__pagination__page-range-total"></span>
      </div>
    </div>
    <button class="dds__button dds__button--tertiary dds__button--sm dds__pagination__next-page" aria-label="Next page">
      <span class="dds__pagination__next-page-label">Next</span>
    </button>
    <button
      class="dds__button dds__button--tertiary dds__button--sm dds__button__icon dds__pagination__last-page"
      aria-label="Last page"
    ></button>
  </div>
</div>

Copy code

View the pagination demo and code in Vanilla.

Pagination

Status

Contents

What's new

Anatomy

Contents

Contents

Usage

On-page

Embedded

Sizes

Standards

Accessibility

Contents

Contents

Live demo

You are now entering a live demo of the component.

Vanilla

Contents

Pagination

Status

Contents

What's newCopy link to this section

AnatomyCopy link to this section

Contents

Vanilla

What's new

Anatomy