Navigation - Contents list

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

Open this default contents list example in new window
Copy default contents list code 
<nav class="nhsuk-contents-list" role="navigation" aria-label="Pages in this guide">
  <h2 class="nhsuk-u-visually-hidden">Contents</h2>
  <ol class="nhsuk-contents-list__list">
    <li class="nhsuk-contents-list__item" aria-current="page">
      <span class="nhsuk-contents-list__current">What is AMD?</span>
    </li>
    <li class="nhsuk-contents-list__item">
      <a class="nhsuk-contents-list__link" href="#">Symptoms</a>
    </li>
    <li class="nhsuk-contents-list__item">
      <a class="nhsuk-contents-list__link" href="#">Getting diagnosed</a>
    </li>
    <li class="nhsuk-contents-list__item">
      <a class="nhsuk-contents-list__link" href="#">Treatments</a>
    </li>
    <li class="nhsuk-contents-list__item">
      <a class="nhsuk-contents-list__link" href="#">Living with AMD</a>
    </li>
  </ol>
</nav>
Close default contents list 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 contents list
Name Type Required Description
Name items Type array Required true Description Array of content list items objects.
Name items[].href Type string Required true Description href value to use within each content list item label.
Name items[].text Type string Required true Description Text to use within each content list item label.
Name current Type boolean Required false Description Set the current active page.
Name classes Type string Required false Description Classes to add to the content list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to items in the content list.
Copy default contents list code 
{% from 'contents-list/macro.njk' import contentsList %}

{{ contentsList({
  items: [
    {
      href: "#",
      text: "What is AMD?",
      current: "true"
    },
    {
      href: "#",
      text: "Symptoms"
    },
    {
      href: "#",
      text: "Getting diagnosed"
    }
    ,
    {
      href: "#",
      text: "Treatments"
    }
    ,
    {
      href: "#",
      text: "Living with AMD"
    }
  ]
}) }}
Close default contents list code

When to use a contents list

Use a contents list at the top 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. The example on this page is from the nhs.uk page about age-related macular degeneration.

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

When not to use a contents list

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

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

How to use a contents list

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

Keep links short and descriptive. Links that are too long (more than 2 lines) make it difficult for users to scan the list.

Page titles must reflect the subject of the page (for example, "Treatment"), with the overall subject of the section as the sub-header (for example, "Age-related macular degeneration (AMD)"). This is so users are clear where they have navigated to.

Accessibility

The list of links is surrounded by a <nav> element to show that they are navigation links. This element has an aria-label attribute with the value Pages in this guide. Screen readers that support this attribute will read this out and that makes it clear what the list of links is.

There is also a visually hidden heading title Contents which screen readers will read 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 contents lists in grouped information pages, like the AMD page, not on forms.

Users understood and engaged with the contents list navigation and said that it fitted how they thought the content would be made up.

The active link formatting helped users know where they were.

Some users said that the page titles helped them orientate themselves, so they knew they were in the right place. Some felt that the links helped them understand what information there was and choose what was relevant to them.

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