Pagination

Pagination is navigation for paginated content.

Default (Bounded)

Component Preview

Component Code


<nav aria-label="Pagination" class="usa-pagination">
  <ul class="usa-pagination__list">
    <li class="usa-pagination__item usa-pagination__arrow">
      <a href="javascript:void(0);" class="usa-pagination__link usa-pagination__previous-page" aria-label="Previous page">
        <svg class="usa-icon" aria-hidden="true" role="img">
          <use href="/civic-guide/uswds/img/sprite.svg#navigate_before"></use>
        </svg>
        <span class="usa-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 1">1</a>
    </li>
    <li class="usa-pagination__item usa-pagination__overflow" aria-label="ellipsis indicating non-visible pages">
      <span>…</span>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 9">9</a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button usa-current" aria-label="Page 10" aria-current="page">10</a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 11">11</a>
    </li>
    <li class="usa-pagination__item usa-pagination__overflow" aria-label="ellipsis indicating non-visible pages">
      <span>…</span>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Last page, page 24">24</a>
    </li>
    <li class="usa-pagination__item usa-pagination__arrow">
      <a href="javascript:void(0);" class="usa-pagination__link usa-pagination__next-page" aria-label="Next page">
        <span class="usa-pagination__link-text">Next </span>
        <svg class="usa-icon" aria-hidden="true" role="img">
          <use href="/civic-guide/uswds/img/sprite.svg#navigate_next"></use>
        </svg>
      </a>
    </li>
  </ul>
</nav>

Unbounded

Component Preview

Component Code


<nav aria-label="Pagination" class="usa-pagination">
  <ul class="usa-pagination__list">
    <li class="usa-pagination__item usa-pagination__arrow">
      <a href="javascript:void(0);" class="usa-pagination__link usa-pagination__previous-page" aria-label="Previous page">
        <svg class="usa-icon" aria-hidden="true" role="img">
          <use href="/civic-guide/uswds/img/sprite.svg#navigate_before"></use>
        </svg>
        <span class="usa-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 1">1</a>
    </li>
    <li class="usa-pagination__item usa-pagination__overflow" aria-label="ellipsis indicating non-visible pages">
      <span>…</span>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 9">9</a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button usa-current" aria-label="Page 10" aria-current="page">10</a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 11">11</a>
    </li>
    <li class="usa-pagination__item usa-pagination__page-no">
      <a href="javascript:void(0);" class="usa-pagination__button" aria-label="Page 12">12</a>
    </li>
    <li class="usa-pagination__item usa-pagination__overflow" aria-label="ellipsis indicating non-visible pages">
      <span>…</span>
    </li>
    <li class="usa-pagination__item usa-pagination__arrow">
      <a href="javascript:void(0);" class="usa-pagination__link usa-pagination__next-page" aria-label="Next page">
        <span class="usa-pagination__link-text">Next </span>
        <svg class="usa-icon" aria-hidden="true" role="img">
          <use href="/civic-guide/uswds/img/sprite.svg#navigate_next"></use>
        </svg>
      </a>
    </li>
  </ul>
</nav>

Guidance

When to use the pagination component

Search results.: Pagination is most commonly used with paginated search results. The component works with both bounded (discrete number of pages) and unbounded (uncalculated number of pages) result sets.
Multi-page collections of related items.: Splitting a large collection of related items into individual pages can improve browsability and scannability. Common examples include articles related to a category or tag, content archives, and history or activity.

When to consider something else

Meaningful page groupings.: If you have long content split meaningfully, or grouped by subject or theme, use conventional navigation like Side navigation.
Steps in a sequence.: If you need to indicate progress in a series of steps that must be completed in succession, like an onboarding flow, consider using the step indicator component.
Short collections.: 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.

Usability guidance

Show the size of the paginated set.: Users want to know the length of a paginated section. Always show the last page as the last item in the pagination navigation for bounded sets.
Highlight the current page.: Pagination shows the current page the user is on in relation to the entire collection of pages.
Always include the first, previous, and next pages.: Users should always be able to navigate to each of these pages from any page in the set.
Show navigation items in a single line.: Don't split the navigation items over multiple lines. Avoid using Pagination in any context where it would be more than one line long.
Indicate any missing pages.: Whenever there are pages missing, indicate them with an indicator like a non-selectable ellipsis.

Accessibility guidance

Use the nav element.: Use a wrapping <nav> element to identify Pagination as a navigation section to screen readers.
Use a unique, descriptive ARIA label.: Provide a descriptive ARIA label for any Pagination component's <nav> element that describes its purpose.
Voice the current page.: Use aria-current="page" on the current page's link item to properly voice the current page for screen readers.
Voice the word "page" before page numbers.: Use aria-label="page [#]" on each page link to be explicit that the numbers are links to page numbers.

USWDS Documentation

For more guidance, view the USWDS Pagination Component Documentation.

Settings

Variable	Description
`$theme-pagination-background-color`	The background color of the entire pagination component.
`$theme-pagination-breakpoint`	Breakpoint at which full pagination displays.
`$theme-pagination-button-border-radius`	Default pagination button border radius.
`$theme-pagination-button-border-width`	Width of button border.
`$theme-pagination-font-family`	Default font family for pagination.

Variants

This component has no modifier class variants. The bounded vs unbounded distinction is determined by whether or not a last page link is included.

Type	Description
Bounded	Has a discrete number of pages. Shows the last page as the final navigation item.
Unbounded	Has no calculated last page (e.g., large search results sorted by relevance). Shows an ellipsis at the end instead of a last page number.