Section navigation
Overview
Use the section navigation component to help a user navigate across pages of closely related content, that have been grouped in context, within a main section.
Example Section Navigation contents
Nunjucks
{% from "components/section-navigation/_macro.njk" import onsSectionNavigation %}
{{
onsSectionNavigation({
"id": "section-menu",
"currentPath": "#section-1",
"itemsList": [
{
"text": "Section 1",
"url": "#section-1"
},
{
"text": "Section 2",
"url": "#0"
},
{
"text": "Section 3",
"url": "#0"
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the <nav> element of the component |
| classes | string | false | Additional classes for the <nav> element |
| hiddenTitle | string | false | The value of the visually hidden <h2> element for screen readers. Defaults to "Pages in this section". |
| hiddenTitleId | string | false | The value of the visually hidden title ID. Necessary if you have multiple section navs. Defaults to "section-menu-nav-title". |
| variants | string | false | To adjust the orientation of the component using available variant “vertical” |
| currentPath | string | true (unless tabQuery set) | Path to the current active page |
| tabQuery | string | true (unless currentPath set) | Query parameter in the URL for the current active page |
| title | string | false | The title/header to display in the section navigation element (only for entries without sections) |
| sections | Array<Item> | false | An array of sections for the component |
| headingLevel | int | false | Number used to determine the heading level of the title to ensure it has the correct semantic order on the page. Defaults to 2 |
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | false | The title/header to display in each section in the navigation element |
| itemsList | Array<Item> | true | An array of list items to display in the section navigation list element |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Additional classes for the list item element |
| url | string | true | The URL for the HTML href attribute for the link |
| text | string | true | The text for the link |
| anchors | Array<Anchors> | false | An array of sub-section list anchors |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The HTML id of the heading tag on the page to link to |
| text | string | true | The text for the anchor link |
HTML
<nav class="ons-section-nav" id="section-menu" aria-labelledby="section-menu-nav-title">
<h2 class="ons-u-vh" id="section-menu-nav-title">Pages in this section</h2>
<ul class="ons-section-nav__list">
<li class="ons-section-nav__item ons-section-nav__item--active">
<a class="ons-section-nav__link ons-section-nav__item-header" href="#section-1" aria-current="location">Section
1</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#0">Section 2</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#0">Section 3</a>
</li>
</ul>
</nav>When not to use this component
Do not use this component to help users navigate pages of content that are not closely related or that a user might search a website or service for.
If you want to group together related content within a single page, use tabs.
How to use this component
This component can be implemented with main navigation in the Header.
It can also be used without any parent level navigation to help users switch across pages of the same type. For example, moving between different views on a survey list (such as: completed, to do and archived).
Variants
Vertical
Use the parameter 'variants': 'vertical' to display the navigation vertically.
Use this variant where you need to include subsections, or the content is broken down into many different pages.
Example Section Navigation Vertical contents
Nunjucks
{% from "components/section-navigation/_macro.njk" import onsSectionNavigation %}
{{
onsSectionNavigation({
"variants": "vertical",
"id": "section-menu",
"currentPath": "#section-6",
"sections":[
{
"title": "Section Title",
"itemsList": [
{
"text": "Section 1",
"url": "#section-1",
"anchors": [
{
"text": "Sub section 1",
"url": "#sub-section-1"
},
{
"text": "Sub section 2",
"url": "#sub-section-2"
},
{
"text": "Sub section 3",
"url": "#sub-section-3"
}
]
},
{
"text": "Section 2",
"url": "#section-2"
},
{
"text": "Section 3",
"url": "#section-3"
},
{
"text": "Section 4",
"url": "#section-4"
}
]
},
{
"title": "Section Title",
"itemsList": [
{
"text": "Section 5",
"url": "#section-5"
},
{
"text": "Section 6",
"url": "#section-6",
"anchors": [
{
"text": "Sub section 1",
"url": "#sub-section-1"
},
{
"text": "Sub section 2",
"url": "#sub-section-2"
},
{
"text": "Sub section 3",
"url": "#sub-section-3"
}
]
},
{
"text": "Section 7",
"url": "#0"
},
{
"text": "Section 8",
"url": "#0"
}
]
}
]
})
}}
Nunjucks macro options
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | false | The HTML id of the <nav> element of the component |
| classes | string | false | Additional classes for the <nav> element |
| hiddenTitle | string | false | The value of the visually hidden <h2> element for screen readers. Defaults to "Pages in this section". |
| hiddenTitleId | string | false | The value of the visually hidden title ID. Necessary if you have multiple section navs. Defaults to "section-menu-nav-title". |
| variants | string | false | To adjust the orientation of the component using available variant “vertical” |
| currentPath | string | true (unless tabQuery set) | Path to the current active page |
| tabQuery | string | true (unless currentPath set) | Query parameter in the URL for the current active page |
| title | string | false | The title/header to display in the section navigation element (only for entries without sections) |
| sections | Array<Item> | false | An array of sections for the component |
| headingLevel | int | false | Number used to determine the heading level of the title to ensure it has the correct semantic order on the page. Defaults to 2 |
| Name | Type | Required | Description |
|---|---|---|---|
| title | string | false | The title/header to display in each section in the navigation element |
| itemsList | Array<Item> | true | An array of list items to display in the section navigation list element |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Additional classes for the list item element |
| url | string | true | The URL for the HTML href attribute for the link |
| text | string | true | The text for the link |
| anchors | Array<Anchors> | false | An array of sub-section list anchors |
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | true | The HTML id of the heading tag on the page to link to |
| text | string | true | The text for the anchor link |
HTML
<nav class="ons-section-nav ons-section-nav--vertical" id="section-menu" aria-labelledby="section-menu-nav-title">
<h2 class="ons-u-vh" id="section-menu-nav-title">Pages in this section</h2>
<div class="ons-section-nav__sub">
<h3 class="ons-u-fs-r--b
ons-u-mb-s">Section Title</h3>
<ul class="ons-section-nav__list">
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#section-1">Section 1</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#section-2">Section 2</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#section-3">Section 3</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#section-4">Section 4</a>
</li>
</ul>
</div>
<div class="ons-section-nav__sub">
<h3 class="ons-u-fs-r--b
ons-u-mb-s">Section Title</h3>
<ul class="ons-section-nav__list">
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#section-5">Section 5</a>
</li>
<li class="ons-section-nav__item ons-section-nav__item--active">
<a class="ons-section-nav__link ons-section-nav__item-header" href="#section-6" aria-current="location">Section
6</a>
<ul class="ons-section-nav__sub-items ons-list ons-list--dashed ons-u-mt-2xs ons-u-mb-2xs">
<li class="ons-section-nav__item ons-list__item">
<a href="#sub-section-1" class="ons-section-nav__link ons-list__link">Sub section 1</a>
</li>
<li class="ons-section-nav__item ons-list__item">
<a href="#sub-section-2" class="ons-section-nav__link ons-list__link">Sub section 2</a>
</li>
<li class="ons-section-nav__item ons-list__item">
<a href="#sub-section-3" class="ons-section-nav__link ons-list__link">Sub section 3</a>
</li>
</ul>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#0">Section 7</a>
</li>
<li class="ons-section-nav__item">
<a class="ons-section-nav__link" href="#0">Section 8</a>
</li>
</ul>
</div>
</nav>Help improve this page
Let us know how we could improve this page, or share your user research findings. Discuss the ‘Section navigation’ component on GitHub (opens in a new tab)