Pagination

navigationUSWDS-derived

Navigation for moving between pages of a multi-page content set.

Reference: USWDS documentation ↗

Variants

Default

<nav class="flex-pagination" aria-label="Pagination">
  <ul class="flex-pagination__list">
    <li class="flex-pagination__item flex-pagination__item--previous">
      <a href="/results?page=3" class="flex-pagination__link" aria-label="Previous page">
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_before">
          </use>
        </svg>
        <span class="flex-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="flex-pagination__item"><a href="/results?page=1" class="flex-pagination__button" aria-label="Page 1">1</a></li>
    <li class="flex-pagination__item"><span class="flex-pagination__overflow" aria-hidden="true">...</span></li>
    <li class="flex-pagination__item"><a href="/results?page=3" class="flex-pagination__button" aria-label="Page 3">3</a></li>
    <li class="flex-pagination__item flex-pagination__item--current"><a href="/results?page=4" class="flex-pagination__button flex-pagination__button--current" aria-label="Page 4, current page" aria-current="page">4</a></li>
    <li class="flex-pagination__item"><a href="/results?page=5" class="flex-pagination__button" aria-label="Page 5">5</a></li>
    <li class="flex-pagination__item"><span class="flex-pagination__overflow" aria-hidden="true">...</span></li>
    <li class="flex-pagination__item"><a href="/results?page=10" class="flex-pagination__button" aria-label="Page 10">10</a></li>
    <li class="flex-pagination__item flex-pagination__item--next">
      <a href="/results?page=5" class="flex-pagination__link" aria-label="Next page">
        <span class="flex-pagination__link-text">Next</span>
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_next">
          </use>
        </svg>
      </a>
    </li>
  </ul>
</nav>

Few Pages

<nav class="flex-pagination" aria-label="Pagination">
  <ul class="flex-pagination__list">
    <li class="flex-pagination__item flex-pagination__item--previous">
      <a href="/results?page=1" class="flex-pagination__link" aria-label="Previous page">
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_before">
          </use>
        </svg>
        <span class="flex-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="flex-pagination__item"><a href="/results?page=1" class="flex-pagination__button" aria-label="Page 1">1</a></li>
    <li class="flex-pagination__item flex-pagination__item--current"><a href="/results?page=2" class="flex-pagination__button flex-pagination__button--current" aria-label="Page 2, current page" aria-current="page">2</a></li>
    <li class="flex-pagination__item"><a href="/results?page=3" class="flex-pagination__button" aria-label="Page 3">3</a></li>
    <li class="flex-pagination__item flex-pagination__item--next">
      <a href="/results?page=3" class="flex-pagination__link" aria-label="Next page">
        <span class="flex-pagination__link-text">Next</span>
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_next">
          </use>
        </svg>
      </a>
    </li>
  </ul>
</nav>

First Page

<nav class="flex-pagination" aria-label="Pagination">
  <ul class="flex-pagination__list">
    <li class="flex-pagination__item flex-pagination__item--current"><a href="/results?page=1" class="flex-pagination__button flex-pagination__button--current" aria-label="Page 1, current page" aria-current="page">1</a></li>
    <li class="flex-pagination__item"><a href="/results?page=2" class="flex-pagination__button" aria-label="Page 2">2</a></li>
    <li class="flex-pagination__item"><span class="flex-pagination__overflow" aria-hidden="true">...</span></li>
    <li class="flex-pagination__item"><a href="/results?page=10" class="flex-pagination__button" aria-label="Page 10">10</a></li>
    <li class="flex-pagination__item flex-pagination__item--next">
      <a href="/results?page=2" class="flex-pagination__link" aria-label="Next page">
        <span class="flex-pagination__link-text">Next</span>
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_next">
          </use>
        </svg>
      </a>
    </li>
  </ul>
</nav>

Last Page

<nav class="flex-pagination" aria-label="Pagination">
  <ul class="flex-pagination__list">
    <li class="flex-pagination__item flex-pagination__item--previous">
      <a href="/results?page=9" class="flex-pagination__link" aria-label="Previous page">
        <svg class="flex-icon" aria-hidden="true" focusable="false">
          <use href="/static/sprite.svg#navigate_before">
          </use>
        </svg>
        <span class="flex-pagination__link-text">Previous</span>
      </a>
    </li>
    <li class="flex-pagination__item"><a href="/results?page=1" class="flex-pagination__button" aria-label="Page 1">1</a></li>
    <li class="flex-pagination__item"><span class="flex-pagination__overflow" aria-hidden="true">...</span></li>
    <li class="flex-pagination__item"><a href="/results?page=9" class="flex-pagination__button" aria-label="Page 9">9</a></li>
    <li class="flex-pagination__item flex-pagination__item--current"><a href="/results?page=10" class="flex-pagination__button flex-pagination__button--current" aria-label="Page 10, current page" aria-current="page">10</a></li>
  </ul>
</nav>

Contract

Class mapping

USWDS	Flex	Notes
`usa-pagination`	`.flex-pagination`	Pagination nav wrapper
`usa-pagination__list`	`.flex-pagination__list`	Pagination list
`usa-pagination__item`	`.flex-pagination__item`	Pagination list item
`usa-pagination__button`	`.flex-pagination__button`	Page number button/link
`usa-current (on pagination)`	`.flex-pagination__button--current`	Current page indicator
`usa-pagination__overflow`	`.flex-pagination__overflow`	Ellipsis overflow indicator
`usa-pagination__previous-page`	`.flex-pagination__item--previous`	Previous page arrow
`usa-pagination__next-page`	`.flex-pagination__item--next`	Next page arrow

Verified properties

font-familyfont-sizeline-heightdisplayjustify-contentlist-style-typecolor

Intentional differences

text-decoration: ours = none, USWDS = underline

USWDS inherits underline from browser default for <a> tags; we explicitly remove it for page number buttons

Behavior promises

○ Current page is visually highlighted with dark background
○ Overflow ellipsis shown for large page counts
○ Previous button hidden on first page
○ Next button hidden on last page

Source CSS

/* flex-pagination — USWDS Pagination conformance
   Features: previous/next arrows, current page, overflow ellipsis */

.flex-pagination {
  margin-block: 1rem;
  font-size: 1.06rem;
  line-height: 1.5;
  color: var(--flex-color-text);
  background-color: var(--flex-color-bg);
  display: flex;
  justify-content: center;

  & .flex-icon {
    block-size: 1.13rem;
    inline-size: 1.13rem;
  }
}

/* --- List --- */

.flex-pagination__list {
  margin-block: 0;
  list-style-type: none;
  padding-inline-start: 0;
  align-items: center;
  display: flex;
  flex-flow: row nowrap;
  justify-content: center;
  inline-size: auto;
}

/* --- Item --- */

.flex-pagination__item {
  display: inline-flex;
  block-size: 2.5rem;
  justify-content: center;
  line-height: 1;
  margin-inline: 0.25rem;
  min-inline-size: 2.5rem;
  flex: 1 0 auto;
}

/* --- Previous / Next --- */

.flex-pagination__item--previous {
  margin-inline-end: 1.25rem;
}

.flex-pagination__item--next {
  margin-inline-start: 1.25rem;
}

/* --- Link (previous/next) --- */

.flex-pagination__link {
  align-items: center;
  color: var(--flex-color-link);
  display: inline-flex;
  text-decoration: none;
  gap: 0.25rem;

  &:hover,
  &:focus,
  &:active {
    color: var(--flex-color-link-hover);
  }

  &:visited {
    color: var(--flex-color-link);
  }

  &:focus {
    outline: 0.25rem solid var(--flex-color-focus);
    outline-offset: 0;
  }
}

.flex-pagination__link-text {
  display: inline;
}

/* --- Button (page numbers) --- */

.flex-pagination__button {
  align-items: center;
  border-color: rgb(27 27 27 / 20%); /* @uswds ink at 20% opacity */
  border-radius: 0.25rem;
  border-style: solid;
  border-width: 1px;
  color: var(--flex-color-link);
  display: inline-flex;
  justify-content: center;
  padding: 0.5rem;
  inline-size: 100%;
  text-decoration: none;

  &:hover,
  &:focus,
  &:active {
    color: var(--flex-color-link-hover);
    border-color: var(--flex-color-link-hover);
  }

  &:focus {
    outline: 0.25rem solid var(--flex-color-focus);
    outline-offset: 0;
  }
}

/* --- Current page --- */

.flex-pagination__button--current {
  background-color: var(--flex-color-text);
  border-color: transparent;
  color: var(--flex-color-bg);

  &:hover,
  &:focus,
  &:active {
    background-color: var(--flex-color-text);
    color: var(--flex-color-bg);
  }
}

/* --- Overflow ellipsis --- */

.flex-pagination__overflow {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  inline-size: 100%;
  block-size: 100%;
  user-select: none;
}