Pagination

Component status:Ready

Pagination is used to navigate from page to page in paginated content, with a control for navigating to the next or previous page.

Examples

Default

The Default Pagination component is used to break up large sets of data across multiple pages. It is commonly used to navigate through items returned from a search or filtering operation.

<nav role="navigation" aria-label="Pagination" class="bux-pagination">
    <ul class="bux-pagination__list">
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--previous" href="#" aria-label="Go to previous page"></a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 1">1</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 2">2</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--current" href="#" aria-label="Current page, page 3" aria-current="true">3</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 4">4</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 5">5</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--next" href="#" aria-label="Go to next page"></a>
        </li>
    </ul>
</nav>

<nav role="navigation" aria-label="Pagination"
     class="bux-pagination{% if modifier %} bux-pagination--{{ modifier }}{% endif %}">

	<ul class="bux-pagination__list">

		{# Display previous link if we"re not on the first page. #}
		{% if previous_page %}
			<li class="bux-pagination__item">
				<a class="bux-pagination__link bux-pagination__link--previous"
           href="{{ previous_page }}" aria-label="Go to previous page"></a>
			</li>
		{% endif %}

		{# Display elipsis if truncate_start. #}
		{% if truncate_start == true %}
			<li class="bux-pagination__item">
				<span class="bux-pagination__link bux-pagination__link--truncated" aria-hidden="true"></span>
			</li>
		{% endif %}

        {% for key, page in pages %}
            <li class="bux-pagination__item">
            {% if current_page == key %}
              <a class="bux-pagination__link bux-pagination__link--current"
                 href="{{ page }}" aria-label="Current page, page {{ key }}" aria-current="true">
                {{- key -}}
              </a>
            {% else %}
              <a class="bux-pagination__link"
                 href="{{ page }}" aria-label="Go to page {{ key }}">
                {{- key -}}
              </a>
            {% endif %}
            </li>
        {% endfor %}

		{# Display elipsis if truncate_end. #}
		{% if truncate_end == true %}
			<li class="bux-pagination__item">
				<span class="bux-pagination__link bux-pagination__link--truncated" aria-hidden="true"></span>
			</li>
		{% endif %}

		{# Display next link if we"re not on the last page. #}
		{% if next_page %}
			<li class="bux-pagination__item">
				<a class="bux-pagination__link bux-pagination__link--next"
           href="{{ next_page }}" aria-label="Go to next page"></a>
			</li>
		{% endif %}
	</ul>
</nav>

{# Default pagination to be used in a Drupal 9 theme. #}

{% if items %}
  <nav role="navigation" aria-label="Pagination" class="bux-pagination{% if modifier %} bux-pagination--{{ modifier }}{% endif %}">
    <ul class="bux-pagination__list">

      {# Print previous item if we are not on the first page. #}
      {% if items.previous %}
        <li class="bux-pagination__item bux-pagination__item--previous">
          <a class="bux-pagination__link bux-pagination__link--previous" href="{{ items.previous.href }}" aria-label="Go to previous page" rel="prev"{{ items.previous.attributes|without('href', 'title', 'rel') }}>
          </a>
        </li>
      {% endif %}

      {# Add an ellipsis if there are further previous pages. #}
      {% if ellipses.previous %}
        <li class="bux-pagination__item" role="presentation">
          <span class="bux-pagination__link bux-pagination__link--truncated" aria-hidden="true"></span>
        </li>
      {% endif %}

      {# Now generate the actual pager piece. #}
      {% for key, item in items.pages %}
        <li class="bux-pagination__item">
        {% if current == key %}
          <a class="bux-pagination__link bux-pagination__link--current" href="{{ item.href }}" aria-label="Current page, page {{ key }}" aria-current="true">
            {{- key -}}
          </a>
        {% else %}
          <a class="bux-pagination__link" href="{{ item.href }}" aria-label="Go to page {{ key }}">
            {{- key -}}
          </a>
        {% endif %}
        </li>
      {% endfor %}

      {# Add an ellipsis if there are further next pages. #}
      {% if ellipses.next %}
        <li class="bux-pagination__item" role="presentation">
          <span class="bux-pagination__link bux-pagination__link--truncated" aria-hidden="true"></span>
        </li>
      {% endif %}

      {# Print next item if we are not on the last page. #}
      {% if items.next %}
        <li class="bux-pagination__item bux-pagination__item--next">
          <a class="bux-pagination__link bux-pagination__link--next" href="{{ items.next.href }}" aria-label="Go to next page" rel="next"{{ items.next.attributes|without('href', 'title', 'rel') }}>
          </a>
        </li>
      {% endif %}
      
    </ul>
  </nav>
{% endif %}

Alternate Pagination

An alternate pagination style with a more subtle hover effect.

<nav role="navigation" aria-label="Pagination" class="bux-pagination bux-pagination--alt">
    <ul class="bux-pagination__list">
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--previous" href="#" aria-label="Go to previous page"></a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 1">1</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 2">2</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--current" href="#" aria-label="Current page, page 3" aria-current="true">3</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 4">4</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 5">5</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--next" href="#" aria-label="Go to next page"></a>
        </li>
    </ul>
</nav>

Reverse Pagination

Pagination for use on a dark background.

<nav role="navigation" aria-label="Pagination" class="bux-pagination bux-pagination--reverse">
    <ul class="bux-pagination__list">
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--previous" href="#" aria-label="Go to previous page"></a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 1">1</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 2">2</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--current" href="#" aria-label="Current page, page 3" aria-current="true">3</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 4">4</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 5">5</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--next" href="#" aria-label="Go to next page"></a>
        </li>
    </ul>
</nav>

Truncated Pagination

Behavior of the pagination when there are more pages than can be displayed at one time.

<nav role="navigation" aria-label="Pagination" class="bux-pagination">
    <ul class="bux-pagination__list">
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--previous" href="#" aria-label="Go to previous page"></a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 1">1</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 2">2</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 3">3</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--current" href="#" aria-label="Current page, page 4" aria-current="true">4</a>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link" href="#" aria-label="Go to page 5">5</a>
        </li>
        <li class="bux-pagination__item">
            <span class="bux-pagination__link bux-pagination__link--truncated" aria-hidden="true"></span>
        </li>
        <li class="bux-pagination__item">
            <a class="bux-pagination__link bux-pagination__link--next" href="#" aria-label="Go to next page"></a>
        </li>
    </ul>
</nav>

Document Pagination

The Document Pagination component is used for page-by-page navigation through content that is meant to be viewed in sequential order. It is often used for content such as books, manuals, or courses.

<nav aria-label="Document pages" class="bux-doc-pagination">
    <div class="bux-doc-pagination__item bux-doc-pagination__item--prev">
        <a href="" class="bux-doc-pagination__link bux-doc-pagination__link--prev" rel="prev">
            <div class="bux-doc-pagination__label bux-doc-pagination__label--prev">
                Page 3
            </div>
        </a>
    </div>
    <div class="bux-doc-pagination__item bux-doc-pagination__item--next">
        <a href="" class="bux-doc-pagination__link bux-doc-pagination__link--next" rel="next">
            <div class="bux-doc-pagination__label bux-doc-pagination__label--next">
                Page 5
            </div>
        </a>
    </div>
</nav>

<nav aria-label="Document pages" class="bux-doc-pagination">
	{% if previous_page %}
		<div class="bux-doc-pagination__item bux-doc-pagination__item--prev">
			<a href="{{ previous_page.url }}" class="bux-doc-pagination__link bux-doc-pagination__link--prev" rel="prev">
				<div class="bux-doc-pagination__label bux-doc-pagination__label--prev">
					{{ previous_page.label }}
				</div>
			</a>
		</div>
	{% endif %}
	{% if next_page %}
		<div class="bux-doc-pagination__item bux-doc-pagination__item--next">
			<a href="{{ next_page.url }}" class="bux-doc-pagination__link bux-doc-pagination__link--next" rel="next">
				<div class="bux-doc-pagination__label bux-doc-pagination__label--next">
					{{ next_page.label }}
				</div>
			</a>
		</div>
	{% endif %}
</nav>

Usage

Dos

• Use on websites where users are looking for specific pieces of content, such as search results, articles related to a tag, or archives
• Pagination is good for page load since the content on the page is limited by what is shown for each page

Don’ts

• Don’t use when users are exploring content or browsing aimlessly for something interesting; consider infinite scrolling instead
  • Infinite scrolling will continue to roll out relevant content in a way that is efficient, digestible, and interruption-free
• Don't use more than five pages in the page list. If the document or collection has more than five pages, use Truncated Pagination instead

Implementation Notes

Javascript

• The current page in the pagination list must have the aria-current role set to 'page'
• Pagination must be in a nav landmark

Accessibility

• When using the Reverse variant, the background color must have a 4.5:1 contrast ratio with white (#FFFFFF)
• Pagination references
  • GOV.UK Design System Pagination See sample HTML
  • U.S. Web Design System (USWDS) Pagination

References

• Infinite Scrolling: When to Use It, When to Avoid It
• Pagination vs. Infinite Scroll: Which Is Better for Your Content?