Skip to main content

Table of contents

Important information:
This component requires documentation.

Table of contents - simple

<aside class="toc-container" role="complementary">
  <a class="skip__link" href="#0">Skip to guide content</a>
  <nav class="toc" aria-label="Pages in this guide">
    <h2 class="toc__title u-fs-r--b u-mb-s">Contents</h2>
    <ol class="list list--dashed u-mb-m">
      <li class="list__item " aria-current="true">
        Overview</li>
      <li class="list__item ">
        <a href="#0" class="list__link ">Who should take part and why</a>
      </li>
      <li class="list__item ">
        <a href="#0" class="list__link ">How your information is used</a>
      </li>
      <li class="list__item ">
        <a href="#0" class="list__link ">The 2019 Census Rehearsal</a>
      </li>
      <li class="list__item ">
        <a href="#0" class="list__link ">Online census</a>
      </li>
    </ol>
  </nav>
</aside>
Nunjucks macro options
Name Type Required Description
Title string true A title for the TOC e.g. “Contents”
ariaLabel string false Accessible label to provide context to contents e.g. “Links to page sections”. Defaults to Table of contents
skipLink Skip link (ref) true Settings for the skip to content link that allows users to avoid reading out the TOC on each page
lists Array<list> true An array of list items to render.

Lists

Name Type Required Description
listHeading string false A heading that can be added between TOC link list items
listHeadingHidden string false Accessible hidden text to provide context to the heading
itemsList Array<itemsList> true An array of list item links

itemsList

Name Type Required Description
url string true URL that contains the id of the content heading to link to
text string true Text to display for the list item
{% from "components/table-of-contents/_macro.njk" import onsTableOfContents %}
{{-
    onsTableOfContents({
        "title": 'Contents',
        "ariaLabel": 'Pages in this guide',
        "skipLink": {
            "url": "#0",
            "text": 'Skip to guide content'
        },
        "itemsList": [
            {
                "url": '#0',
                "text": 'Overview',
                "current": true
            },
            {
                "url": '#0',
                "text": 'Who should take part and why'
            },
            {
                "url": '#0',
                "text": 'How your information is used'
            },
            {
                "url": '#0',
                "text": 'The 2019 Census Rehearsal'
            },
            {
                "url": '#0',
                "text": 'Online census'
            }
        ]
    })
}}

{% macro onsTableOfContents(params) %}
  {% from "components/lists/_macro.njk" import onsList %}
  {% from "components/skip-to-content/_macro.njk" import onsSkipToContent %}
  <aside class="toc-container" role="complementary">
    {{
        onsSkipToContent({
            "url": params.skipLink.url,
            "text": params.skipLink.text
        })
    }}
    <nav class="toc" aria-label="{{ params.ariaLabel | default("Table of contents") }}">
      <h2 class="toc__title u-fs-r--b u-mb-s">{{ params.title }}</h2>
      {% if params.lists is defined and params.lists %}
        {% for list in params.lists %}
          {% if list.listHeading is defined and list.listHeading %}
            <h3 class="u-fs-r u-mb-xs">{{ list.listHeading }}<span class="u-vh"> {{ list.listHeadingHidden }}</span>:</h3>
          {% endif %}
          {{
              onsList({
                  "element": 'ol',
                  "classes": 'list--dashed u-mb-m',
                  "itemsList": list.itemsList
              })
          }}
        {% endfor %}
      {% elif params.itemsList is defined and params.itemsList %}
        {{
            onsList({
                "element": 'ol',
                "classes": 'list--dashed u-mb-m',
                "itemsList": params.itemsList
            })
        }}
      {% endif %}
    </nav>
  </aside>
{% endmacro %}

.toc-container {
  border-bottom: 1px solid $color-grey-15;
  margin-bottom: 2rem;
  padding-bottom: 1rem;
}

Table of contents - multiple sections

<aside class="toc-container" role="complementary">
  <a class="skip__link" href="#0">Skip to guide content</a>
  <nav class="toc" aria-label="Links to page sections">
    <h2 class="toc__title u-fs-r--b u-mb-s">Contents</h2>
    <h3 class="u-fs-r u-mb-xs">Household questions<span class="u-vh"> help topics</span>:</h3>
    <ol class="list list--dashed u-mb-m">
      <li class="list__item ">
        <a href="#household1" class="list__link ">Household and who lives here</a>
      </li>
      <li class="list__item ">
        <a href="#household2" class="list__link ">Housing, sex and GI</a>
      </li>
    </ol>
    <h3 class="u-fs-r u-mb-xs">Individual questions<span class="u-vh"> help topics</span>:</h3>
    <ol class="list list--dashed u-mb-m">
      <li class="list__item ">
        <a href="#individual1" class="list__link ">Name, date of birth and marital status</a>
      </li>
      <li class="list__item ">
        <a href="#individual2" class="list__link ">Language, religion and ethnicity</a>
      </li>
      <li class="list__item ">
        <a href="#individual3" class="list__link ">Address, health and sexual orientation</a>
      </li>
      <li class="list__item ">
        <a href="#individual4" class="list__link ">Education and employment</a>
      </li>
    </ol>
  </nav>
</aside>
Nunjucks macro options
Name Type Required Description
Title string true A title for the TOC e.g. “Contents”
ariaLabel string false Accessible label to provide context to contents e.g. “Links to page sections”. Defaults to Table of contents
skipLink Skip link (ref) true Settings for the skip to content link that allows users to avoid reading out the TOC on each page
lists Array<list> true An array of list items to render.

Lists

Name Type Required Description
listHeading string false A heading that can be added between TOC link list items
listHeadingHidden string false Accessible hidden text to provide context to the heading
itemsList Array<itemsList> true An array of list item links

itemsList

Name Type Required Description
url string true URL that contains the id of the content heading to link to
text string true Text to display for the list item
{% from "components/table-of-contents/_macro.njk" import onsTableOfContents %}
{{-
    onsTableOfContents({
        "title": 'Contents',
        "ariaLabel": 'Links to page sections',
        "skipLink": {
            "url": '#0',
            "text": 'Skip to guide content'
        },
        "lists": [
            {
                "listHeading": 'Household questions',
                "listHeadingHidden": 'help topics',
                "itemsList": [
                    {
                        "url": '#household1',
                        "text": 'Household and who lives here'
                    },
                    {
                        "url": '#household2',
                        "text": 'Housing, sex and GI'
                    }
                ]
            },
            {
                "listHeading": 'Individual questions',
                "listHeadingHidden": 'help topics',
                "itemsList": [
                    {
                        "url": '#individual1',
                        "text": 'Name, date of birth and marital status'
                    },
                    {
                        "url": '#individual2',
                        "text": 'Language, religion and ethnicity'
                    },
                    {
                        "url": '#individual3',
                        "text": 'Address, health and sexual orientation'
                    },
                    {
                        "url": '#individual4',
                        "text": 'Education and employment'
                    }
                ]
            }
        ]
    })
}}

{% macro onsTableOfContents(params) %}
  {% from "components/lists/_macro.njk" import onsList %}
  {% from "components/skip-to-content/_macro.njk" import onsSkipToContent %}
  <aside class="toc-container" role="complementary">
    {{
        onsSkipToContent({
            "url": params.skipLink.url,
            "text": params.skipLink.text
        })
    }}
    <nav class="toc" aria-label="{{ params.ariaLabel | default("Table of contents") }}">
      <h2 class="toc__title u-fs-r--b u-mb-s">{{ params.title }}</h2>
      {% if params.lists is defined and params.lists %}
        {% for list in params.lists %}
          {% if list.listHeading is defined and list.listHeading %}
            <h3 class="u-fs-r u-mb-xs">{{ list.listHeading }}<span class="u-vh"> {{ list.listHeadingHidden }}</span>:</h3>
          {% endif %}
          {{
              onsList({
                  "element": 'ol',
                  "classes": 'list--dashed u-mb-m',
                  "itemsList": list.itemsList
              })
          }}
        {% endfor %}
      {% elif params.itemsList is defined and params.itemsList %}
        {{
            onsList({
                "element": 'ol',
                "classes": 'list--dashed u-mb-m',
                "itemsList": params.itemsList
            })
        }}
      {% endif %}
    </nav>
  </aside>
{% endmacro %}

.toc-container {
  border-bottom: 1px solid $color-grey-15;
  margin-bottom: 2rem;
  padding-bottom: 1rem;
}

Help improve this component

Let us know how we could improve this component or share your user research findings.

Discuss ‘Table of contents’ component on GitHub