Navigation - Pagination

Use pagination to allow users to navigate between related pages, for example about a single condition.

Open this default pagination example in new window
Copy default pagination code 
<nav class="nhsuk-pagination" role="navigation" aria-label="Pagination">
  <ul class="nhsuk-list nhsuk-pagination__list">
    <li class="nhsuk-pagination-item--previous">
      <a class="nhsuk-pagination__link nhsuk-pagination__link--prev" href="#">
        <span class="nhsuk-pagination__title">Previous</span>
        <span class="nhsuk-u-visually-hidden">:</span>
        <span class="nhsuk-pagination__page">Treatments</span>
        <svg class="nhsuk-icon nhsuk-icon__arrow-left" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" width="34" height="34">
          <path d="M4.1 12.3l2.7 3c.2.2.5.2.7 0 .1-.1.1-.2.1-.3v-2h11c.6 0 1-.4 1-1s-.4-1-1-1h-11V9c0-.2-.1-.4-.3-.5h-.2c-.1 0-.3.1-.4.2l-2.7 3c0 .2 0 .4.1.6z"></path>
        </svg>
      </a>
    </li>
    <li class="nhsuk-pagination-item--next">
      <a class="nhsuk-pagination__link nhsuk-pagination__link--next" href="#">
        <span class="nhsuk-pagination__title">Next</span>
        <span class="nhsuk-u-visually-hidden">:</span>
        <span class="nhsuk-pagination__page">Symptoms</span>
        <svg class="nhsuk-icon nhsuk-icon__arrow-right" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true" width="34" height="34">
          <path d="M19.6 11.66l-2.73-3A.51.51 0 0 0 16 9v2H5a1 1 0 0 0 0 2h11v2a.5.5 0 0 0 .32.46.39.39 0 0 0 .18 0 .52.52 0 0 0 .37-.16l2.73-3a.5.5 0 0 0 0-.64z"></path>
        </svg>
      </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 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 pagination code 
{% from 'pagination/macro.njk' import pagination %}

{{ pagination({
  "previousUrl": "#",
  "previousPage": "Treatments",
  "nextUrl": "#",
  "nextPage": "Symptoms"
}) }}
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

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.

Research

We tested pagination in grouped information pages in 3 labs in summer 2018. We haven't tested it in forms.

In a user research lab, 4 out of 5 users, including a user with a very low level of digital skill, used pagination to navigate through the pages. They understood that it was associated with the navigation at the top of the page.

Users found that the pagination reflected the way they read content and their mental model of the structure of the content.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

If you have any questions, get in touch with the service manual team.

Updated: February 2019