Table of contents
Overview
Use a table of contents to help users jump between sections of content on a single page or pages of a guide.
Example Table Of Contents Single contents
Nunjucks
{% 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'
},
"lists": [
{
"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'
}
]
}
]
})
-}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | A title for the component, for example, “Contents” |
| ariaLabel | string | false | Descriptive landmark ARIA label to give a screen reader user greater understanding of its purpose. Defaults to “Table of contents”. |
| skipLink | Skip to content (ref) | false | Settings for the skip to content link that allows users to avoid reading out the table of contents on each page. Required for any table of contents repeated on multiple pages, such as a guide |
| lists | array<list> | true (unless itemsList set) | An array of lists for the component |
| itemsList | array<itemsList> | true (unless lists set) | An array of list items for the component |
| Name | Type | Required | Description |
|---|---|---|---|
| listHeading | string | false | A sub-heading for each list |
| listHeadingHidden | string | false | Visually hidden text following the sub-heading to provide context for screen readers |
| itemsList | array<itemsList> | true | An array of list item links |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The URL or path for the page or heading to link to |
| text | string | true | Text for the list item |
HTML
<aside class="ons-table-of-contents-container" role="complementary">
<a class="ons-skip-to-content" href="#0">Skip to guide content</a>
<nav class="ons-table-of-contents" aria-label="Pages in this guide">
<h2 class="ons-table-of-contents__title ons-u-fs-r--b ons-u-mb-s">Contents</h2>
<ol class="ons-list ons-u-mb-l ons-list--dashed">
<li class="ons-list__item" aria-current="true"> Overview </li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">Who should take part and why</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">How your information is used</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">The 2019 Census Rehearsal</a>
</li>
<li class="ons-list__item">
<a href="#0" class="ons-list__link">Online census</a>
</li>
</ol>
</nav>
</aside>When not to use this component
Do not use the in-page variant of this component if the height of the table of contents will be greater than the height of the viewport.
The list will not scroll independently of the page content because research shows some users find this confusing.
Variants
Grouped table of contents
Example Table Of Contents Grouped contents
Nunjucks
{% 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'
}
]
}
]
})
-}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | A title for the component, for example, “Contents” |
| ariaLabel | string | false | Descriptive landmark ARIA label to give a screen reader user greater understanding of its purpose. Defaults to “Table of contents”. |
| skipLink | Skip to content (ref) | false | Settings for the skip to content link that allows users to avoid reading out the table of contents on each page. Required for any table of contents repeated on multiple pages, such as a guide |
| lists | array<list> | true (unless itemsList set) | An array of lists for the component |
| itemsList | array<itemsList> | true (unless lists set) | An array of list items for the component |
| Name | Type | Required | Description |
|---|---|---|---|
| listHeading | string | false | A sub-heading for each list |
| listHeadingHidden | string | false | Visually hidden text following the sub-heading to provide context for screen readers |
| itemsList | array<itemsList> | true | An array of list item links |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The URL or path for the page or heading to link to |
| text | string | true | Text for the list item |
HTML
<aside class="ons-table-of-contents-container" role="complementary">
<a class="ons-skip-to-content" href="#0">Skip to guide content</a>
<nav class="ons-table-of-contents" aria-label="Links to page sections">
<h2 class="ons-table-of-contents__title ons-u-fs-r--b ons-u-mb-s">Contents</h2>
<h3 class="ons-u-fs-r ons-u-mb-2xs"> Household questions<span class="ons-u-vh"> help topics</span>: </h3>
<ol class="ons-list ons-u-mb-l ons-list--dashed">
<li class="ons-list__item">
<a href="#household1" class="ons-list__link">Household and who lives here</a>
</li>
<li class="ons-list__item">
<a href="#household2" class="ons-list__link">Housing, sex and GI</a>
</li>
</ol>
<h3 class="ons-u-fs-r ons-u-mb-2xs"> Individual questions<span class="ons-u-vh"> help topics</span>: </h3>
<ol class="ons-list ons-u-mb-l ons-list--dashed">
<li class="ons-list__item">
<a href="#individual1" class="ons-list__link">Name, date of birth and marital status</a>
</li>
<li class="ons-list__item">
<a href="#individual2" class="ons-list__link">Language, religion and ethnicity</a>
</li>
<li class="ons-list__item">
<a href="#individual3" class="ons-list__link">Address, health and sexual orientation</a>
</li>
<li class="ons-list__item">
<a href="#individual4" class="ons-list__link">Education and employment</a>
</li>
</ol>
</nav>
</aside>In-page table of contents
Use this variant to help users quickly jump to sections of a long page of content.
As the user scrolls down the page, the table of contents will remain accessible at the top of the viewport and will highlight the subheading of the section in view.
! Warning:
You will need to open the following example in a new tab to see it highlight the section in view.
Example Table Of Contents Sticky contents
Nunjucks
{% from "components/table-of-contents/_macro.njk" import onsTableOfContents %}
<div class="ons-page__container ons-container">
<div class="ons-grid ons-js-toc-container">
<div class="ons-grid__col ons-grid__col--sticky@m ons-col-4@m">
{{-
onsTableOfContents({
"title": 'Contents',
"ariaLabel": 'Sections in this page',
"itemsList": [
{
"url": '#section1',
"text": 'What is the census?'
},
{
"url": '#section2',
"text": 'The online census has now closed'
},
{
"url": '#section3',
"text": 'What happens after Census Day'
},
{
"url": '#section4',
"text": 'The census in Northern Ireland and Scotland'
},
{
"url": '#section5',
"text": 'The last census'
}
]
})
-}}
</div>
<div class="ons-grid__col ons-col-7@m ons-push-1@m">
<section id="section1">
<h2>What is the census?</h2>
<p>
The census is a survey that happens every 10 years and gives us a picture of all the people and households in England
and Wales.
</p>
<p>
Your answers to the census questions will help organisations make decisions on planning and funding public services in
your area, including transport, education and healthcare.
</p>
</section>
<section id="section2">
<h2>The online census has now closed</h2>
<p>Census Day was on Sunday 21 March 2021.</p>
<p>If you still have a paper census questionnaire, fill it in as soon as you can and return it to FREEPOST, Census 2021.</p>
</section>
<section id="section3">
<h2>What happens after Census Day</h2>
<p>
Two follow-up surveys, the <a href="#0">Census Coverage Survey</a> and the <a href="#0">Census Quality Survey</a>, help
to improve the quality and accuracy of the census results.
</p>
<p>
Over the next year, we work hard to process the answers from all the census questionnaires. This is so that we can
publish the initial Census 2021 findings one year after the census and the main releases two years after the census.
</p>
<p>
To make sure the Census 2021 statistics we publish meet the needs of those who use them, we also run an outputs
consultation.
</p>
</section>
<section id="section4">
<h2>The census in Northern Ireland and Scotland</h2>
<p>The Office for National Statistics (ONS) runs the census in England and Wales.</p>
<p>
If you live in Northern Ireland, visit the Northern Ireland Statistics Agency (NISRA) census website to find out about
the census for Northern Ireland.
</p>
<p>
If you live in Scotland, visit the National Records of Scotland census website to find out how to take part in the
census for Scotland.
</p>
</section>
<section id="section5">
<h2>The last census</h2>
<p>
The last census took place in 2011. Many people and organisations used information from the 2011 Census in a variety of
ways.
</p>
<p>
For example, Bristol City Council used it to inform decisions on how to fund local housing improvements. It was also
essential for the charity Redbridge Council for Voluntary Services to help people from ethnic minority groups learn more
about dementia.
</p>
<p>
To read more about the benefits that information from the 2011 Census helped to create, visit the Office for National
Statistics (ONS) website.
</p>
<p>
The Census Coverage Survey (CCS) was a short, separate survey that we at the Office for National Statistics (ONS)
started six to eight weeks after Census Day.
</p>
<p>
The CCS helps make sure everyone is counted and our census results are as accurate as possible. It asked similar
questions to the main census, just fewer of them, at addresses in a selection of postcodes across England and Wales.
</p>
<p>The CCS has now closed.</p>
</section>
</div>
</div>
</div>
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | true | A title for the component, for example, “Contents” |
| ariaLabel | string | false | Descriptive landmark ARIA label to give a screen reader user greater understanding of its purpose. Defaults to “Table of contents”. |
| skipLink | Skip to content (ref) | false | Settings for the skip to content link that allows users to avoid reading out the table of contents on each page. Required for any table of contents repeated on multiple pages, such as a guide |
| lists | array<list> | true (unless itemsList set) | An array of lists for the component |
| itemsList | array<itemsList> | true (unless lists set) | An array of list items for the component |
| Name | Type | Required | Description |
|---|---|---|---|
| listHeading | string | false | A sub-heading for each list |
| listHeadingHidden | string | false | Visually hidden text following the sub-heading to provide context for screen readers |
| itemsList | array<itemsList> | true | An array of list item links |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The URL or path for the page or heading to link to |
| text | string | true | Text for the list item |
HTML
<div class="ons-page__container ons-container">
<div class="ons-grid ons-js-toc-container">
<div class="ons-grid__col ons-grid__col--sticky@m ons-col-4@m">
<aside class="ons-table-of-contents-container" role="complementary">
<nav class="ons-table-of-contents" aria-label="Sections in this page">
<h2 class="ons-table-of-contents__title ons-u-fs-r--b ons-u-mb-s">Contents</h2>
<ol class="ons-list ons-u-mb-l ons-list--dashed">
<li class="ons-list__item">
<a href="#section1" class="ons-list__link">What is the census?</a>
</li>
<li class="ons-list__item">
<a href="#section2" class="ons-list__link">The online census has now closed</a>
</li>
<li class="ons-list__item">
<a href="#section3" class="ons-list__link">What happens after Census Day</a>
</li>
<li class="ons-list__item">
<a href="#section4" class="ons-list__link">The census in Northern Ireland and Scotland</a>
</li>
<li class="ons-list__item">
<a href="#section5" class="ons-list__link">The last census</a>
</li>
</ol>
</nav>
</aside>
</div>
<div class="ons-grid__col ons-col-7@m ons-push-1@m">
<section id="section1">
<h2>What is the census?</h2>
<p> The census is a survey that happens every 10 years and gives us a picture of all the people and households
in England and Wales. </p>
<p> Your answers to the census questions will help organisations make decisions on planning and funding public
services in your area, including transport, education and healthcare. </p>
</section>
<section id="section2">
<h2>The online census has now closed</h2>
<p>Census Day was on Sunday 21 March 2021.</p>
<p>If you still have a paper census questionnaire, fill it in as soon as you can and return it to FREEPOST,
Census 2021.</p>
</section>
<section id="section3">
<h2>What happens after Census Day</h2>
<p> Two follow-up surveys, the <a href="#0">Census Coverage Survey</a> and the <a href="#0">Census Quality
Survey</a>, help to improve the quality and accuracy of the census results. </p>
<p> Over the next year, we work hard to process the answers from all the census questionnaires. This is so that
we can publish the initial Census 2021 findings one year after the census and the main releases two years
after the census. </p>
<p> To make sure the Census 2021 statistics we publish meet the needs of those who use them, we also run an
outputs consultation. </p>
</section>
<section id="section4">
<h2>The census in Northern Ireland and Scotland</h2>
<p>The Office for National Statistics (ONS) runs the census in England and Wales.</p>
<p> If you live in Northern Ireland, visit the Northern Ireland Statistics Agency (NISRA) census website to find
out about the census for Northern Ireland. </p>
<p> If you live in Scotland, visit the National Records of Scotland census website to find out how to take part
in the census for Scotland. </p>
</section>
<section id="section5">
<h2>The last census</h2>
<p> The last census took place in 2011. Many people and organisations used information from the 2011 Census in a
variety of ways. </p>
<p> For example, Bristol City Council used it to inform decisions on how to fund local housing improvements. It
was also essential for the charity Redbridge Council for Voluntary Services to help people from ethnic
minority groups learn more about dementia. </p>
<p> To read more about the benefits that information from the 2011 Census helped to create, visit the Office for
National Statistics (ONS) website. </p>
<p> The Census Coverage Survey (CCS) was a short, separate survey that we at the Office for National Statistics
(ONS) started six to eight weeks after Census Day. </p>
<p> The CCS helps make sure everyone is counted and our census results are as accurate as possible. It asked
similar questions to the main census, just fewer of them, at addresses in a selection of postcodes across
England and Wales. </p>
<p>The CCS has now closed.</p>
</section>
</div>
</div>
</div>How to use this variant
To use this variant on a page, you need to:
- place the table of contents in the first of two columns of a grid layout and add the class
.ons-grid__col--sticky@mto thediv - add the class
.ons-js-toc-containerto the<div>which wraps both columns - wrap each section of content in the second column in a
<section>tag with a uniqueid. For example:<section id="section1"> - set a URI fragment as the
urlvalue of each link in the table of contents list, matching theidof the section it links to. For example#section1 - start each section of content with an
<h2>heading matching each link in the table of contents list
Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss ‘Table of contents’ component on GitHub (opens in a new tab)