Navigation - Contents list

Use contents lists to allow users to navigate between related pages.

Open this default contents list example in new window
Copy default contents list code 
<nav class="hs2-contents-list" role="navigation" aria-label="Pages in this guide">
  <h2 class="hs2-u-visually-hidden">Contents</h2>
  <ol class="hs2-contents-list__list">
    <li class="hs2-contents-list__item" aria-current="page">
      <span class="hs2-contents-list__current">Components</span>
    </li>
    <li class="hs2-contents-list__item">
      <a class="hs2-contents-list__link" href="/design-system/components/buttons">Buttons</a>
    </li>
    <li class="hs2-contents-list__item">
      <a class="hs2-contents-list__link" href="/design-system/components/checkboxes">Checkboxes</a>
    </li>
    <li class="hs2-contents-list__item">
      <a class="hs2-contents-list__link" href="/design-system/components/date-input">Date input</a>
    </li>
    <li class="hs2-contents-list__item">
      <a class="hs2-contents-list__link" href="/design-system/components/error-message">Error message</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: "/design-system/components",
      text: "Components",
      current: "true"
    },
    {
      href: "/design-system/components/buttons",
      text: "Buttons"
    },
    {
      href: "/design-system/components/checkboxes",
      text: "Checkboxes"
    }
    ,
    {
      href: "/design-system/components/date-input",
      text: "Date input"
    }
    ,
    {
      href: "/design-system/components/error-message",
      text: "Error message"
    }
  ]
}) }}
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).

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 with the overall subject of the section as the sub-header. 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.