Pagination

Navigates between pages of results.

When to use it

A result set split across pages.

When not to use it

Fewer results than one page holds.

Examples

Each example is a conformance case: every emitter — React, and each framework adapter — is checked against exactly this markup.

first-page

Rendered

HTML

<nav class="gov-pagination" aria-label="Pagination">
  <ol class="gov-pagination__list">
    <li class="gov-pagination__item">
      <a class="gov-pagination__link gov-pagination__link--current" href="?page=1" aria-current="page">
        <span class="gov-visually-hidden">Page </span>1</a>
      </li>
      <li class="gov-pagination__item">
        <a class="gov-pagination__link" href="?page=2">
          <span class="gov-visually-hidden">Page </span>2</a>
        </li>
        <li class="gov-pagination__item">
          <a class="gov-pagination__link" href="?page=3">
            <span class="gov-visually-hidden">Page </span>3</a>
          </li>
        </ol>
        <a class="gov-pagination__link gov-pagination__link--next" href="?page=2" rel="next">Next</a>
      </nav>

{
  "current": 1,
  "total": 3
}

middle-page

Rendered

HTML

<nav class="gov-pagination" aria-label="Pagination">
  <a class="gov-pagination__link gov-pagination__link--previous" href="?page=1" rel="prev">Previous</a>
  <ol class="gov-pagination__list">
    <li class="gov-pagination__item">
      <a class="gov-pagination__link" href="?page=1">
        <span class="gov-visually-hidden">Page </span>1</a>
      </li>
      <li class="gov-pagination__item">
        <a class="gov-pagination__link gov-pagination__link--current" href="?page=2" aria-current="page">
          <span class="gov-visually-hidden">Page </span>2</a>
        </li>
        <li class="gov-pagination__item">
          <a class="gov-pagination__link" href="?page=3">
            <span class="gov-visually-hidden">Page </span>3</a>
          </li>
        </ol>
        <a class="gov-pagination__link gov-pagination__link--next" href="?page=3" rel="next">Next</a>
      </nav>

{
  "current": 2,
  "total": 3
}

last-page

Rendered

HTML

<nav class="gov-pagination" aria-label="Pagination">
  <a class="gov-pagination__link gov-pagination__link--previous" href="?page=2" rel="prev">Previous</a>
  <ol class="gov-pagination__list">
    <li class="gov-pagination__item">
      <a class="gov-pagination__link" href="?page=1">
        <span class="gov-visually-hidden">Page </span>1</a>
      </li>
      <li class="gov-pagination__item">
        <a class="gov-pagination__link" href="?page=2">
          <span class="gov-visually-hidden">Page </span>2</a>
        </li>
        <li class="gov-pagination__item">
          <a class="gov-pagination__link gov-pagination__link--current" href="?page=3" aria-current="page">
            <span class="gov-visually-hidden">Page </span>3</a>
          </li>
        </ol>
      </nav>

{
  "current": 3,
  "total": 3
}

single-page

Rendered

HTML

<nav class="gov-pagination" aria-label="Pagination">
  <ol class="gov-pagination__list">
    <li class="gov-pagination__item">
      <a class="gov-pagination__link gov-pagination__link--current" href="?page=1" aria-current="page">
        <span class="gov-visually-hidden">Page </span>1</a>
      </li>
    </ol>
  </nav>

{
  "current": 1,
  "total": 1
}

Accessibility

Accessible name. The nav landmark label, 'Pagination' by default.

Keyboard behavior
Key	Behavior
`Tab`	Moves through the page links in order.

Real links, so pagination works with no JavaScript and pages are shareable and bookmarkable.
Each number carries a visually hidden 'Page' prefix, so it announces as 'Page 2' rather than '2'.
Previous and Next are omitted at the ends rather than rendered disabled.

Class names

Class names
Role	Class
`base`	`.gov-pagination`
`list`	`.gov-pagination__list`
`item`	`.gov-pagination__item`
`link`	`.gov-pagination__link`
`linkCurrent`	`.gov-pagination__link--current`
`linkPrevious`	`.gov-pagination__link--previous`
`linkNext`	`.gov-pagination__link--next`

View the manifest for this component: packages/manifest/components/pagination.json