Skip to main content
USWDS + Tailwind

Help shape v2! Take a short survey to make this tool better for everyone.

Pagination

Pagination is navigation for paginated content.

Examples

Bounded

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Twig 
{% macro button(page_number, href = '#', is_active = false, is_last = false) %}
  <li class="h-10 min-w-10 inline-flex">
    <a
      href="#"
      class="p-2 w-full flex rounded border border-gray-90/20 text-blue-60v justify-center items-center hover:text-blue-warm-70v hover:border-blue-warm-70v focus:text-blue-warm-70v focus:border-blue-warm-70v focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v aria-[current=page]:bg-gray-90 aria-[current=page]:text-white"
      aria-label="{{ is_last ? 'Last page, page ' ~ page_number : 'Page ' ~ page_number }}"
      {{ is_active ? 'aria-current="page"' }}
    >
      {{- page_number -}}
    </a>
  </li>
{% endmacro %}


{% macro ellipsis() %}
  <li aria-label="ellipsis indicating non-visible pages" class="h-10 min-w-10 p-2 select-none flex items-center justify-center">
    <span>...</span>
  </li>
{% endmacro %}


{% import _self as self %}


<nav aria-label="Pagination" class="@container flex justify-center">
  <ul class="flex space-x-2">


    {% if pagination.current_page != 1 %}
      <li class="h-10 min-w-10 hidden @tablet:inline-flex">
        <a href="#" class="pr-2 mr-3 inline-flex items-center text-blue-60v hover:underline hover:text-blue-warm-70v focus:underline focus:text-blue-warm-70v focus:outline focus:outline-4 focus:outline-blue-40v">
          <span aria-hidden="true" class="icon-[material-symbols--chevron-left] align-middle size-4"></span>
          Previous
        </a>
      </li>
    {% endif %}


    {% if pagination.page_count <= 7 %}


      {% for i in range(1, pagination.page_count) %}
        {{ self.button(i, '', i == pagination.current_page, i == pagination.page_count) }}
      {% endfor %}


    {% else %}


      {% if pagination.current_page <= 4  %}


        {% for i in range(1, 4) %}
          {{ self.button(i,'', i == pagination.current_page, i == pagination.page_count) }}
        {% endfor %}
        {{ self.ellipsis() }}
        {{ self.button(pagination.page_count, '') }}


      {% elseif pagination.current_page >= pagination.page_count - 3 %}


        {{ self.button(1, '') }}
        {{ self.ellipsis() }}
        {% for i in range(pagination.page_count - 4, pagination.page_count) %}
          {{ self.button(i,'', i == pagination.current_page, i == pagination.page_count) }}
        {% endfor %}


      {% else %}


        {{ self.button(1, '') }}
        {{ self.ellipsis() }}


        {% for i in range(pagination.current_page - 1, pagination.current_page + 1) %}
          {{ self.button(i, '', i == pagination.current_page, i == pagination.page_count) }}
        {% endfor %}


        {{ self.ellipsis() }}
        {{ self.button(pagination.page_count, '') }}


      {% endif %}


    {% endif %}


    {% if pagination.current_page != pagination.page_count %}
      <li class="h-10 min-w-10 hidden @tablet:inline-flex">
        <a href="#" class="pl-2 ml-3 inline-flex items-center text-blue-60v hover:underline hover:text-blue-warm-70v focus:underline focus:text-blue-warm-70v focus:outline focus:outline-4 focus:outline-blue-40v">
          Next
          <span aria-hidden="true" class="icon-[material-symbols--chevron-right] align-middle size-4"></span>
        </a>
      </li>
    {% endif %}


  </ul>
</nav>

Unbounded

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Twig 
{% macro button(page_number, href = '#', is_active = false, is_last = false) %}
  <li class="h-10 min-w-10 inline-flex">
    <a
      href="#"
      class="p-2 w-full flex rounded border border-gray-90/20 text-blue-60v justify-center items-center hover:text-blue-warm-70v hover:border-blue-warm-70v focus:text-blue-warm-70v focus:border-blue-warm-70v focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v aria-[current=page]:bg-gray-90 aria-[current=page]:text-white"
      aria-label="{{ is_last ? 'Last page, page ' ~ page_number : 'Page ' ~ page_number }}"
      {{ is_active ? "aria-current='page'" }}
    >
      {{- page_number -}}
    </a>
  </li>
{% endmacro %}


{% macro ellipsis() %}
  <li aria-label="ellipsis indicating non-visible pages" class="h-10 min-w-10 p-2 select-none flex items-center justify-center">
    <span>...</span>
  </li>
{% endmacro %}


{% import _self as self %}


<nav aria-label="Pagination" class="@container flex justify-center">
  <ul class="flex space-x-2">


    {% if pagination.current_page != 1 %}
      <li class="h-10 min-w-10 hidden @tablet:inline-flex">
        <a href="#" class="pr-2 mr-3 inline-flex items-center text-blue-60v hover:underline hover:text-blue-warm-70v focus:underline focus:text-blue-warm-70v focus:outline focus:outline-4 focus:outline-blue-40v">
          <span aria-hidden="true" class="icon-[material-symbols--chevron-left] align-middle size-4"></span>
          Previous
        </a>
      </li>
    {% endif %}


    {% if pagination.current_page <= 5  %}


      {% for i in range(1, 6) %}
        {{ self.button(i,'', i == pagination.current_page, false) }}
      {% endfor %}
      {{ self.ellipsis() }}


    {% else %}


      {{ self.button(1, '') }}
      {{ self.ellipsis() }}
      {% for i in range(pagination.current_page - 1, pagination.current_page + 2) %}
        {{ self.button(i,'', i == pagination.current_page, false) }}
      {% endfor %}
      {{ self.ellipsis() }}


    {% endif %}


    <li class="h-10 min-w-10 hidden @tablet:inline-flex">
      <a href="#" class="pl-2 ml-3 inline-flex items-center text-blue-60v hover:underline hover:text-blue-warm-70v focus:underline focus:text-blue-warm-70v focus:outline focus:outline-4 focus:outline-blue-40v">
        Next
        <span aria-hidden="true" class="icon-[material-symbols--chevron-right] align-middle size-4"></span>
      </a>
    </li>


  </ul>
</nav>

Component API

Pagination is made up of the following elements:

Root

  • This element is automatically appended to the document body, ensuring that this element always properly overlays page contents when opened.

  • aria-label

    Default: 'Breadcrumb'

    Provide a label that describes the type of navigation provided in the nav element.

List

  • <ul>

    Use an <ul> for Pagination Lists. This allows assistive technology to enumerate the items in the pagination and allows shortcuts between list items.

List Items

  • <li>

    Use an <li> for Pagination List Items. This allows assistive technology to enumerate the items in the pagination and allows shortcuts between list items.

  • aria-label

    Default: 'ellipsis indicating non-visible pages'

    When a Pagination List Item contains an Ellipsis, use an aria-label to describe to assistive technology the meaning of the ellipsis item.

  • <a> or <span>

    Use an <a> element when Pagination List Items are clickable. Every item, except Ellipsis elements, should use an <a> element.

    Use a <span> element for Ellipsis elements.

  • aria-current="page"

    Allows screen readers to communicate that the element represents a link to the current page.

    Only use the aria-current attribute on the link element describing the current page.