Skip to main content
U.S. Flag

An official website of the United States government

Pagination

Pagination is navigation for paginated content.

Examples

Loading

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.

React Properties Documentation
NameTypeDefaultDescription
ariaLabelstringDefines aria-label on wrapping Pagination element. Since this exists on a <nav> element, the word "navigation" should be omitted from this label. Optional.
classNamestringClass to be applied to parent <nav> element of Pagination component. Optional.
compactbooleanfalseRenders compact layout. Optional.
currentPagerequirednumberDefines active page in Pagination.
isNavigationHiddenbooleanfalseDetermines if navigation is hidden when current page is the first or last of Pagination page set. Optional.
onPageChangerequired(evt: MouseEvent<Element, MouseEvent>, page: number) => voidA callback function used to handle state changes.
renderHrefrequired(page: number) => stringDefines application-specific routing in url for links.
startLabelTextstringSets custom label on start navigation. Added for language support. Optional.
startAriaLabelstringSets custom ARIA label on start navigation. Added for language support. Label structure should be the equivalent of: Previous Page. Optional.
endLabelTextstringSets custom label on end navigation. Added for language support. Optional.
endAriaLabelstringSets custom ARIA label on end navigation. Added for language support. Label structure should be the equivalent of: Next Page. Optional.
totalPagesrequirednumberSets total number of pages in Pagination component.

Styles

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

CSS variables for pagination
VariableDefault Core Theme Value
--pagination-link__colorhex value: #0071bc--color-primary
--pagination-link__color--hoverhex value: #004f84--color-primary-darker
--pagination-link__color--activehex value: #00395e--color-background-inverse
--pagination-link__color--focushex value: #004f84--color-primary-darker
--pagination-link__color--disabledhex value: #d9d9d9--color-border
--pagination-current-page__colorhex value: #262626--color-base
--pagination-overflow__colorhex value: #5a5a5a--color-gray
--pagination-page-count__colorhex value: #5a5a5a--color-gray

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

  • Use a wrapping <nav> element to identify Pagination as a navigation section.
  • If more than one <nav> element is present on a page, Pagination must have an ARIA label attribute defined on the <nav> element that describes its purpose.
  • Use an unordered list for the navigation items as this allows screen readers to voice the number of elements in the Pagination component.
  • Use aria-current="page" on the current page's element to properly voice the current page for screen readers.
  • Voice the word "page" before the page numbers.
  • If Previous navigation link has keyboard focus, pressing TAB key must move focus to the first pagination page link.
  • If pagination page has keyboard focus, pressing TAB key must move focus to the next pagination page link.
  • If last pagination page has keyboard focus, pressing TAB key must move focus to the Next pagination navigation link.
  • Once a pagination page has been clicked, focus should shift to the top-level piece of content on that page, usually an <h1>.

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Incomplete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Incomplete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete