Pagination

Pagination allows the user to navigate through pages of content.

Considerations

Wrap pagination in a nav component with a label (using aria-label or aria-labelledby) so assistive technology can identify it as a navigation landmark.

Indicate the current page both visually, and using aria-current="page" for assistive tech.

If possible, show the total number of pages to give users a sense of how much content there is.

When on the first or last page, remove the "next"/"previous" button so users can't proceed further in that direction. The best way is to simply omit the link/button. If the button is important for layout, disable it with aria-disabled="true", remove the href attribute, and add role="link". If using a <button>, disable it with the disabled attribute. Read more about this technique.

Save the pagination state in the URL so users can bookmark or share links to specific pages, and use the back button to navigate. Next/previous and page number buttons should use <a> tags, not <button> tags.

Examples

Simple nav

<nav aria-label="{{ title }} - Pages" class="pagination">
  <a href="#" aria-current="page" class="pagination__page">1</a>
  <a href="#" class="pagination__page" rel="next">2</a>
  <a href="#" class="pagination__page">3</a>
  <a href="#" class="pagination__page">4</a>
  <a href="#" class="pagination__control pagination__control--next" rel="next"
    >Next →
  </a>
</nav>

Nav with page gaps and metadata

<nav aria-label="{{ title }} - Pages" class="pagination pagination--fancy">
  <ul class="pagination__list">
    <li class="pagination__control pagination__control--prev">
      <a href="#" rel="prev"> Previous </a>
    </li>
    <li class="pagination__page">
      <a href="#">1</a>
    </li>
    <li class="pagination__space"><span role="separator">&#8230;</span></li>
    <li class="pagination__page">
      <a href="#" rel="prev">7</a>
    </li>
    <li class="pagination__page">
      <a href="#" aria-current="page">8</a>
    </li>
    <li class="pagination__page">
      <a href="#" rel="next">9</a>
    </li>
    <li class="pagination__space"><span role="separator">&#8230;</span></li>
    <li class="pagination__page">
      <a href="#">42</a>
    </li>
    <li class="pagination__control pagination__control--next">
      <a href="#" rel="next"> Next </a>
    </li>
  </ul>

  <span class="pagination__meta">70 - 90 of 436</span>
</nav>

Pagy Support

Roux includes styles for the popular Pagy Ruby gem. Pagy offers a few types of nav views.

Pagy series nav

<nav class="pagy series-nav" aria-label="{{ title }} - Pages">
  <a href="/path?example=123&page=2" rel="prev" aria-label="Previous">←</a>
  <a href="/path?example=123&page=1">1</a>
  <a href="/path?example=123&page=2" rel="prev">2</a>
  <a role="link" aria-disabled="true" aria-current="page">3</a>
  <a href="/path?example=123&page=4" rel="next">4</a>
  <a href="/path?example=123&page=5">5</a>
  <a role="separator" aria-disabled="true">&hellip;</a>
  <a href="/path?example=123&page=50">50</a>
  <a href="/path?example=123&page=4" rel="next" aria-label="Next">→</a>
</nav>

Pagy series nav with limited slots

<nav aria-label="{{ title }} - Pages">
  <ul class="pagy series-nav">
    <li>
      <a
        href="/path?example=123&page=2"
        class="pagination-previous"
        rel="prev"
        aria-label="Previous"
        >←</a
      >
    </li>
    <li>
      <a href="/path?example=123&page=2" class="pagination-link" rel="prev"
        >2</a
      >
    </li>
    <li>
      <a
        role="link"
        class="pagination-link is-current"
        aria-current="page"
        aria-disabled="true"
        >3</a
      >
    </li>
    <li>
      <a href="/path?example=123&page=4" class="pagination-link" rel="next"
        >4</a
      >
    </li>
    <li>
      <a
        href="/path?example=123&page=4"
        class="pagination-next"
        rel="next"
        aria-label="Next"
        >→</a
      >
    </li>
  </ul>
</nav>