Navigation - Contents list

Use a contents list to allow users to navigate between related pages.

Open this default contents list example in new window
Copy default contents list code 
<nav class="hse-contents-list" role="navigation" aria-label="Pages in this guide">
  <h2 class="hse-u-visually-hidden">Contents</h2>
  <ol class="hse-contents-list__list">
    <li class="hse-contents-list__item" aria-current="page">
      <span class="hse-contents-list__current">What is AMD?</span>
    </li>
    <li class="hse-contents-list__item">
      <a class="hse-contents-list__link" href="https://www.hse.ie/conditions/age-related-macular-degeneration-amd/symptoms/">Symptoms</a>
    </li>
    <li class="hse-contents-list__item">
      <a class="hse-contents-list__link" href="https://www.hse.ie/conditions/age-related-macular-degeneration-amd/getting-diagnosed/">Getting diagnosed</a>
    </li>
    <li class="hse-contents-list__item">
      <a class="hse-contents-list__link" href="https://www.hse.ie/conditions/age-related-macular-degeneration-amd/treatment/">Treatments</a>
    </li>
    <li class="hse-contents-list__item">
      <a class="hse-contents-list__link" href="https://www.hse.ie/conditions/age-related-macular-degeneration-amd/living-with-amd/">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: "https://www.hse.ie/conditions/age-related-macular-degeneration-amd/",
      text: "What is AMD?",
      current: "true"
    },
    {
      href: "https://www.hse.ie/conditions/age-related-macular-degeneration-amd/symptoms/",
      text: "Symptoms"
    },
    {
      href: "https://www.hse.ie/conditions/age-related-macular-degeneration-amd/getting-diagnosed/",
      text: "Getting diagnosed"
    }
    ,
    {
      href: "https://www.hse.ie/conditions/age-related-macular-degeneration-amd/treatment/",
      text: "Treatments"
    }
    ,
    {
      href: "https://www.hse.ie/conditions/age-related-macular-degeneration-amd/living-with-amd/",
      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 let users navigate around a group of related pages. It should not be more than 8 pages.

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 guide.

When not to use a contents list

Do not use a contents list on pages which are not grouped together or related. This can confuse users.

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

How to use a contents list

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

Keep links short and descriptive. Links that are too long make it hard for users to scan the list.

Page titles must reflect the subject of the page. For example; "Treatment". The overall subject of the section should be the sub-header. For example; "Age-related macular degeneration (AMD)". This is so users know 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, and what it relates to.

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 current page.

Research

Testing showed that the contents list navigation supported users when the multi-page guide pattern is used consistently.

We use this pattern to describe conditions, using a consistent structure for content.

No more than 8 links should be used in a contents list.

Updated: September 2023