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="Pages" 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="[object Object]" aria-label="Page 1"
        >1</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 2"
        >2</a
      >
    </li>
    <li class="bux-pagination__item">
      <a
        class="bux-pagination__link bux-pagination__link--current"
        href="[object Object]"
        aria-label="Current page, page 3"
        aria-current="true"
        >3</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 4"
        >4</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="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>

{#
Buckeye UX - version 1.0.15
Copyright (C) 2024 The Ohio State University
#}

{# 

Pagination

Available variables:

- modifier:         Sets the pagination variant. Can be null, alt or reverse
- current_page:     Integer for the current page, starting at 1.
- previous_page:    URL of the previous page.
- next_page:        URL of the next page.
- total_pages:      Integer value of the total number of pages, starting at 1.
- pages:            Array containing the URLs of all pages.
- truncate_start:   Boolean. Set to true to truncate pagination at start.
- truncate_end:     Boolean. Set to true to truncate pagination at end.
- truncate_pages:   Array containing a list of pages to truncate.
- zero_based_index: Boolean. Set to true if your system is using zero based
                    indexing.

#}

{% set base = 0 %}

{% if zero_based_index %}{% set base = 1 %}{% endif %}

<nav role="navigation" aria-label="Pages"
     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" role="presentation"></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 + base }}" aria-current="true">
                {{- key + base -}}
              </a>
            {% else %}
              <a class="bux-pagination__link"
                 href="{{ page }}" aria-label="Page {{ key + base }}">
                {{- key + base -}}
              </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" role="presentation"></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="Pages"
  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="[object Object]" aria-label="Page 1"
        >1</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 2"
        >2</a
      >
    </li>
    <li class="bux-pagination__item">
      <a
        class="bux-pagination__link bux-pagination__link--current"
        href="[object Object]"
        aria-label="Current page, page 3"
        aria-current="true"
        >3</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 4"
        >4</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="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>

{#
Buckeye UX - version 1.0.15
Copyright (C) 2024 The Ohio State University
#}

{# 

Pagination

Available variables:

- modifier:         Sets the pagination variant. Can be null, alt or reverse
- current_page:     Integer for the current page, starting at 1.
- previous_page:    URL of the previous page.
- next_page:        URL of the next page.
- total_pages:      Integer value of the total number of pages, starting at 1.
- pages:            Array containing the URLs of all pages.
- truncate_start:   Boolean. Set to true to truncate pagination at start.
- truncate_end:     Boolean. Set to true to truncate pagination at end.
- truncate_pages:   Array containing a list of pages to truncate.
- zero_based_index: Boolean. Set to true if your system is using zero based
                    indexing.

#}

{% set base = 0 %}

{% if zero_based_index %}{% set base = 1 %}{% endif %}

<nav role="navigation" aria-label="Pages"
     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" role="presentation"></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 + base }}" aria-current="true">
                {{- key + base -}}
              </a>
            {% else %}
              <a class="bux-pagination__link"
                 href="{{ page }}" aria-label="Page {{ key + base }}">
                {{- key + base -}}
              </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" role="presentation"></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>

Reverse Pagination

Pagination for use on a dark background.

<nav
  role="navigation"
  aria-label="Pages"
  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="[object Object]" aria-label="Page 1"
        >1</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 2"
        >2</a
      >
    </li>
    <li class="bux-pagination__item">
      <a
        class="bux-pagination__link bux-pagination__link--current"
        href="[object Object]"
        aria-label="Current page, page 3"
        aria-current="true"
        >3</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 4"
        >4</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="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>

{#
Buckeye UX - version 1.0.15
Copyright (C) 2024 The Ohio State University
#}

{# 

Pagination

Available variables:

- modifier:         Sets the pagination variant. Can be null, alt or reverse
- current_page:     Integer for the current page, starting at 1.
- previous_page:    URL of the previous page.
- next_page:        URL of the next page.
- total_pages:      Integer value of the total number of pages, starting at 1.
- pages:            Array containing the URLs of all pages.
- truncate_start:   Boolean. Set to true to truncate pagination at start.
- truncate_end:     Boolean. Set to true to truncate pagination at end.
- truncate_pages:   Array containing a list of pages to truncate.
- zero_based_index: Boolean. Set to true if your system is using zero based
                    indexing.

#}

{% set base = 0 %}

{% if zero_based_index %}{% set base = 1 %}{% endif %}

<nav role="navigation" aria-label="Pages"
     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" role="presentation"></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 + base }}" aria-current="true">
                {{- key + base -}}
              </a>
            {% else %}
              <a class="bux-pagination__link"
                 href="{{ page }}" aria-label="Page {{ key + base }}">
                {{- key + base -}}
              </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" role="presentation"></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>

Truncated Pagination

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

<nav role="navigation" aria-label="Pages" 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="[object Object]" aria-label="Page 1"
        >1</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 2"
        >2</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 3"
        >3</a
      >
    </li>
    <li class="bux-pagination__item">
      <a
        class="bux-pagination__link bux-pagination__link--current"
        href="[object Object]"
        aria-label="Current page, page 4"
        aria-current="true"
        >4</a
      >
    </li>
    <li class="bux-pagination__item">
      <a class="bux-pagination__link" href="[object Object]" aria-label="Page 5"
        >5</a
      >
    </li>

    <li class="bux-pagination__item">
      <span
        class="bux-pagination__link bux-pagination__link--truncated"
        aria-hidden="true"
        role="presentation"
      ></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>

{#
Buckeye UX - version 1.0.15
Copyright (C) 2024 The Ohio State University
#}

{# 

Pagination

Available variables:

- modifier:         Sets the pagination variant. Can be null, alt or reverse
- current_page:     Integer for the current page, starting at 1.
- previous_page:    URL of the previous page.
- next_page:        URL of the next page.
- total_pages:      Integer value of the total number of pages, starting at 1.
- pages:            Array containing the URLs of all pages.
- truncate_start:   Boolean. Set to true to truncate pagination at start.
- truncate_end:     Boolean. Set to true to truncate pagination at end.
- truncate_pages:   Array containing a list of pages to truncate.
- zero_based_index: Boolean. Set to true if your system is using zero based
                    indexing.

#}

{% set base = 0 %}

{% if zero_based_index %}{% set base = 1 %}{% endif %}

<nav role="navigation" aria-label="Pages"
     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" role="presentation"></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 + base }}" aria-current="true">
                {{- key + base -}}
              </a>
            {% else %}
              <a class="bux-pagination__link"
                 href="{{ page }}" aria-label="Page {{ key + base }}">
                {{- key + base -}}
              </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" role="presentation"></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>

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>

{#
Buckeye UX - version 1.0.15
Copyright (C) 2024 The Ohio State University
#}

{# 

Doc Pagination

Available variables:

- previous_page:        Array containing the details of the previous page.
- previous_page.url:    URL for the previous page.
- previous_page.label:  Label for the previous page.
- next_page:            Array containing the details of the next page.
- next_page.url:        URL for the next page.
- next_page.label:      Label for the next page.

#}

<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?