Navigation - Pagination

Use pagination to allow users to navigate between related pages.

Open this default pagination example in new window
Copy default pagination code 
<nav class="hs2-pagination " aria-label="Pagination (Page 5 of 35)">
  <div class="hs2-pagination__position">Page 5 of 35</div>
  <ul class="hs2-pagination__items">

    <li class="hs2-pagination__item hs2-pagination__item--previous">
      <a href="#0" class="hs2-pagination__link" rel="prev" aria-label="Go to the previous page (Page 4)">Previous</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to the first page (Page 1)">1</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to page 4" rel="prev">4</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--current">
      <a href="#0" class="hs2-pagination__link" aria-current="true" aria-label="Current page (Page 5 of 35)">5</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to page 6" rel="next">6</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to the last page (Page 35)">35</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--next">
      <a href="#0" class="hs2-pagination__link" rel="next" aria-label="Go to the next page (Page 6)">Next</a>
    </li>

  </ul>
</nav>
Close default pagination code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default pagination
Name Type Required Description
Name pages Type array Required true Description Settings for each page
Name pages[].url Type string Required true Description The URL for the HTML href attribute for the page link
Name pages[].current Type boolean Required true Description Set to “true” for the current loaded page link
Name previous Type string Required true Description Text label for the “Previous” link
Name next Type string Required true Description Text label for the “Next” link
Name classes Type string Required false Description Classes to add to the pagination HTML nav element
Name hideRangeIndicator Type boolean Required false Description Set to “true” to hide the range indicator on larger screens
Copy default pagination code 
{% from "pagination/macro.njk" import pagination %}

{{
    pagination({
        "previous": "Previous",
        "next": "Next",
        "pages": [
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0",
                "current": true
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            }
        ]
    })
}}
Close default pagination code

When to use pagination

Use pagination at the bottom of the page to allow users to navigate around a small group of related pages (up to 8 pages), for example a group of pages about a specific condition.

If you're using pagination, you should also use a contents list at the top of the page. The 2 components make up the multi-page navigation pattern.

When not to use pagination

Do not use pagination on pages which aren't grouped together or "related" as this is likely to confuse users.

Do not use pagination in a transactional service or a form. We use other components instead, including:

How to use pagination

The pagination component should be left aligned after the content on each page that you are paginating.

For smaller screens, show the range indicator and hide the page numbers.

For larger screens, show page numbers for:

  • the current page
  • one page immediately before and after the current page (when applicable)
  • the first page and the last page

Use ellipses (...) to replace any skipped pages. For example:

  • [1] 2 … 10
  • 1 [2] 3 … 10
  • 1 2 [3] 4 … 10
  • 1 2 3 [4] 5 … 10
  • 1 ... 4 [5] 6 … 10
  • 1 … 5 [6] 7 ... 10
  • 1 … 6 [7] 8 9 10
  • 1 … 7 [8] 9 10
  • 1 … 8 [9] 10
  • 1 … 9 [10]

Variants

Long pagination (no range indicator)

Use this variant when there are up to ten pages of content.

The range indicator will be hidden on larger screens. However, it will still show on smaller screens as the page numbers do not.

Open this long pagination pagination example in new window
Copy long pagination pagination code 
<nav class="hs2-pagination  hs2-pagination--no-indicator" aria-label="Pagination (Page 5 of 10)">
  <div class="hs2-pagination__position">Page 5 of 10</div>
  <ul class="hs2-pagination__items">

    <li class="hs2-pagination__item hs2-pagination__item--previous">
      <a href="#page4" class="hs2-pagination__link" rel="prev" aria-label="Go to the previous page (Page 4)">Previous</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#page1" class="hs2-pagination__link" aria-label="Go to the first page (Page 1)">1</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#page4" class="hs2-pagination__link" aria-label="Go to page 4" rel="prev">4</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--current">
      <a href="#page5" class="hs2-pagination__link" aria-current="true" aria-label="Current page (Page 5 of 10)">5</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#page6" class="hs2-pagination__link" aria-label="Go to page 6" rel="next">6</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#page10" class="hs2-pagination__link" aria-label="Go to the last page (Page 10)">10</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--next">
      <a href="#page6" class="hs2-pagination__link" rel="next" aria-label="Go to the next page (Page 6)">Next</a>
    </li>

  </ul>
</nav>
Close long pagination pagination code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for long pagination pagination
Name Type Required Description
Name pages Type array Required true Description Settings for each page
Name pages[].url Type string Required true Description The URL for the HTML href attribute for the page link
Name pages[].current Type boolean Required true Description Set to “true” for the current loaded page link
Name previous Type string Required true Description Text label for the “Previous” link
Name next Type string Required true Description Text label for the “Next” link
Name classes Type string Required false Description Classes to add to the pagination HTML nav element
Name hideRangeIndicator Type boolean Required false Description Set to “true” to hide the range indicator on larger screens
Copy long pagination pagination code 
{% from "pagination/macro.njk" import pagination %}

{{
    pagination({
        "previous": "Previous",
        "next": "Next",
        "hideRangeIndicator": true,
        "pages": [
            {
                "url": "#page1"
            },
            {
                "url": "#page2"
            },
            {
                "url": "#page3"
            },
            {
                "url": "#page4"
            },
            {
                "url": "#page5",
                "current": true
            },
            {
                "url": "#page6"
            },
            {
                "url": "#page7"
            },
            {
                "url": "#page8"
            },
            {
                "url": "#page9"
            },
            {
                "url": "#page10"
            }
        ]
    })
}}
Close long pagination pagination code

Pager

Open this default pager example in new window
Copy default pager code 
<nav class="hs2-pager" role="navigation" aria-label="pager">
  <ul class="hs2-list hs2-pager__list">
    <li class="hs2-pager-item--previous">
      <a class="hs2-pager__link hs2-pager__link--prev" href="#">
        <span class="hs2-pager__title">Previous</span>
        <span class="hs2-u-visually-hidden">:</span>
        <span class="hs2-pager__page">The route</span>
        <svg class="hs2-icon hs2-icon__arrow-left" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" width="34" height="34">
          <path d="M6.69995 6.82499L8.59995 8.69999L6.62495 10.675L21.325 10.675L21.325 13.325L6.62495 13.325L8.59995 15.3L6.69995 17.175L1.54995 12L6.69995 6.82499Z"></path>
        </svg>
      </a>
    </li>
    <li class="hs2-pager-item--next">
      <a class="hs2-pager__link hs2-pager__link--next" href="#">
        <span class="hs2-pager__title">Next</span>
        <span class="hs2-u-visually-hidden">:</span>
        <span class="hs2-pager__page">Building HS2</span>
        <svg class="hs2-icon hs2-icon__arrow-right" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" width="34" height="34">
          <path d="M17.3 17.175L15.4 15.3L17.375 13.325H2.67505V10.675H17.375L15.4 8.70001L17.3 6.82501L22.4501 12L17.3 17.175Z"></path>
        </svg>
      </a>
    </li>
  </ul>
</nav>
Close default pager code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default pager
Name Type Required Description
Name previousUrl Type string Required true Description The value of the previous link href attribute.
Name previousPage Type string Required true Description The text of the previous link.
Name nextUrl Type string Required true Description The value of the next link href attribute.
Name nextPage Type string Required true Description The text of the next link.
Name classes Type string Required false Description Classes to add to the pagination container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the pagination container.
Copy default pager code 
{% from 'pager/macro.njk' import pager %}

{{ pager({
  "previousUrl": "#",
  "previousPage": "The route",
  "nextUrl": "#",
  "nextPage": "Building HS2"
}) }}
Close default pager code

How to use the pager

Use a contents list at the top of the page together with pagination at the bottom of each page.

Use the word "Previous" with an arrow left and a link to the previous page. Use the word Next" with an arrow right and a link to the next page. Use the same page titles as in the contents list.

Accessibility

The pagination components are surrounded by a <nav> element to show that they are navigation links. This element has an aria-label attribute with the value Pagination. Screen readers that support this attribute will read this.

There is also a visually hidden heading title pagination which will be read by screen readers as a heading to the links.

If the link describes the current page that you are on, then it has the aria-current="page" value to indicate to screen readers that this is the case.

Open this default pagination example in new window
Copy default pagination code 
<nav class="hs2-pagination " aria-label="Pagination (Page 5 of 35)">
  <div class="hs2-pagination__position">Page 5 of 35</div>
  <ul class="hs2-pagination__items">

    <li class="hs2-pagination__item hs2-pagination__item--previous">
      <a href="#0" class="hs2-pagination__link" rel="prev" aria-label="Go to the previous page (Page 4)">Previous</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to the first page (Page 1)">1</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to page 4" rel="prev">4</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--current">
      <a href="#0" class="hs2-pagination__link" aria-current="true" aria-label="Current page (Page 5 of 35)">5</a>
    </li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to page 6" rel="next">6</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--gap">&hellip;</li>

    <li class="hs2-pagination__item">
      <a href="#0" class="hs2-pagination__link" aria-label="Go to the last page (Page 35)">35</a>
    </li>

    <li class="hs2-pagination__item hs2-pagination__item--next">
      <a href="#0" class="hs2-pagination__link" rel="next" aria-label="Go to the next page (Page 6)">Next</a>
    </li>

  </ul>
</nav>
Close default pagination code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default pagination
Name Type Required Description
Name pages Type array Required true Description Settings for each page
Name pages[].url Type string Required true Description The URL for the HTML href attribute for the page link
Name pages[].current Type boolean Required true Description Set to “true” for the current loaded page link
Name previous Type string Required true Description Text label for the “Previous” link
Name next Type string Required true Description Text label for the “Next” link
Name classes Type string Required false Description Classes to add to the pagination HTML nav element
Name hideRangeIndicator Type boolean Required false Description Set to “true” to hide the range indicator on larger screens
Copy default pagination code 
{% from "pagination/macro.njk" import pagination %}

{{
    pagination({
        "previous": "Previous",
        "next": "Next",
        "pages": [
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0",
                "current": true
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            },
            {
                "url": "#0"
            }
        ]
    })
}}
Close default pagination code