Components Horizontal navigation
The horizontal navigation component is a list of secondary navigation links within a service.
<nav class="dwp-horizontal-navigation" aria-label="Horizontal">
<ul class="dwp-horizontal-navigation__list">
<li class="dwp-horizontal-navigation__item">
<a id="l-item-1" href="#l-item-1" class="dwp-horizontal-navigation__link">Item 1</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="l-item-2" href="#l-item-2" class="dwp-horizontal-navigation__link">Item 2</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="l-item-3" href="#l-item-3" class="dwp-horizontal-navigation__link">Item 3</a>
</li>
</ul>
</nav>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.
| Name | Type | Description |
|---|---|---|
| items | array | Required. Array of object navigation items, see items |
| selectedItem | string | URL string to highlight selected navigation item |
| ariaLabel | string | Aria label for navigation, defaults to 'Horizontal' |
| contained | string | Wraps the navigation in a container |
| containerClasses | string | Additional classes to add to the container |
| attributes | object | HTML Attributes (data attributes) to add to the container |
Options for items array object
| Name | Type | Description |
|---|---|---|
| text | string | Required. Value for text of the naivigation link |
| href | string | Required. Value for the href of the navigation link |
| id | string | Value for the id of the navigation link |
{% from "horizontal-navigation/macro.njk" import dwpHorizontalNavigation %}
{{
dwpHorizontalNavigation({
items: [
{
text: "Item 1",
href: "#l-item-1",
id: "l-item-1"
},
{
text: "Item 2",
href: "#l-item-2",
id: "l-item-2"
},
{
text: "Item 3",
href: "#l-item-3",
id: "l-item-3"
}
]
})
}}When to use this component
Use this component when users need to move between related pages within a service.
The horizontal navigation component is for use in internal services. It is intended as secondary navigation: for primary navigation you should use the header navigation component.
It is one of two options for secondary navigation within a service: the other is side navigation.
When not to use this component
You should not use horizontal navigation as the main navigation in a service. Use the Header navigation component instead.
You should not use this component in public-facing services. If a public-facing service needs secondary navigation it may be that its structure is too complex and you should review its information architecture.
Do not use this component for internal links between sections of the same page. If you need to organise large amounts of content on a single page consider the GOV.UK Tabs component instead.
How it works
The horizontal navigation is a list of links to pages within a section of a service. Each link takes the user to a different page and the current page is highlighted.
<nav class="dwp-horizontal-navigation" aria-label="Horizontal">
<ul class="dwp-horizontal-navigation__list">
<li class="dwp-horizontal-navigation__item">
<a id="d-item-1" href="#d-item-1" class="dwp-horizontal-navigation__link">Item 1</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="d-item-2" href="#d-item-2" class="dwp-horizontal-navigation__link">Item 2</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="d-item-3" href="#d-item-3" class="dwp-horizontal-navigation__link">Item 3</a>
</li>
</ul>
</nav>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.
| Name | Type | Description |
|---|---|---|
| items | array | Required. Array of object navigation items, see items |
| selectedItem | string | URL string to highlight selected navigation item |
| ariaLabel | string | Aria label for navigation, defaults to 'Horizontal' |
| contained | string | Wraps the navigation in a container |
| containerClasses | string | Additional classes to add to the container |
| attributes | object | HTML Attributes (data attributes) to add to the container |
Options for items array object
| Name | Type | Description |
|---|---|---|
| text | string | Required. Value for text of the naivigation link |
| href | string | Required. Value for the href of the navigation link |
| id | string | Value for the id of the navigation link |
{% from "horizontal-navigation/macro.njk" import dwpHorizontalNavigation %}
{{
dwpHorizontalNavigation({
items: [
{
text: "Item 1",
href: "#d-item-1",
id: "d-item-1"
},
{
text: "Item 2",
href: "#d-item-2",
id: "d-item-2"
},
{
text: "Item 3",
href: "#d-item-3",
id: "d-item-3"
}
]
})
}}Selected
<nav class="dwp-horizontal-navigation" aria-label="Horizontal">
<ul class="dwp-horizontal-navigation__list">
<li class="dwp-horizontal-navigation__item dwp-horizontal-navigation__item--selected">
<a id="s-item-1" href="#s-item-1" class="dwp-horizontal-navigation__link" aria-current="true">Item 1</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="s-item-2" href="#s-item-2" class="dwp-horizontal-navigation__link">Item 2</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="s-item-3" href="#s-item-3" class="dwp-horizontal-navigation__link">Item 3</a>
</li>
</ul>
</nav>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.
| Name | Type | Description |
|---|---|---|
| items | array | Required. Array of object navigation items, see items |
| selectedItem | string | URL string to highlight selected navigation item |
| ariaLabel | string | Aria label for navigation, defaults to 'Horizontal' |
| contained | string | Wraps the navigation in a container |
| containerClasses | string | Additional classes to add to the container |
| attributes | object | HTML Attributes (data attributes) to add to the container |
Options for items array object
| Name | Type | Description |
|---|---|---|
| text | string | Required. Value for text of the naivigation link |
| href | string | Required. Value for the href of the navigation link |
| id | string | Value for the id of the navigation link |
{% from "horizontal-navigation/macro.njk" import dwpHorizontalNavigation %}
{{
dwpHorizontalNavigation({
selectedItem: "#s-item-1",
items: [
{
text: "Item 1",
href: "#s-item-1",
id: "s-item-1"
},
{
text: "Item 2",
href: "#s-item-2",
id: "s-item-2"
},
{
text: "Item 3",
href: "#s-item-3",
id: "s-item-3"
}
]
})
}}Mobile view
<nav class="dwp-horizontal-navigation" aria-label="Horizontal">
<ul class="dwp-horizontal-navigation__list">
<li class="dwp-horizontal-navigation__item">
<a id="d-item-1-m" href="#d-item-1-m" class="dwp-horizontal-navigation__link">Item 1</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="d-item-2-m" href="#d-item-2-m" class="dwp-horizontal-navigation__link">Item 2</a>
</li>
<li class="dwp-horizontal-navigation__item">
<a id="d-item-3-m" href="#d-item-3-m" class="dwp-horizontal-navigation__link">Item 3</a>
</li>
</ul>
</nav>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.
| Name | Type | Description |
|---|---|---|
| items | array | Required. Array of object navigation items, see items |
| selectedItem | string | URL string to highlight selected navigation item |
| ariaLabel | string | Aria label for navigation, defaults to 'Horizontal' |
| contained | string | Wraps the navigation in a container |
| containerClasses | string | Additional classes to add to the container |
| attributes | object | HTML Attributes (data attributes) to add to the container |
Options for items array object
| Name | Type | Description |
|---|---|---|
| text | string | Required. Value for text of the naivigation link |
| href | string | Required. Value for the href of the navigation link |
| id | string | Value for the id of the navigation link |
{% from "horizontal-navigation/macro.njk" import dwpHorizontalNavigation %}
{{
dwpHorizontalNavigation({
items: [
{
text: "Item 1",
href: "#d-item-1-m",
id: "d-item-1-m"
},
{
text: "Item 2",
href: "#d-item-2-m",
id: "d-item-2-m"
},
{
text: "Item 3",
href: "#d-item-3-m",
id: "d-item-3-m"
}
]
})
}}Accessibility
You can change the description of the navigation by providing an ariaLabel.
When a link item is selected aria-current is set to true: this tells a screen reader which item is selected.
For more about building accessible services see the DWP Accessibility Manual.
Contribute
If you have used or researched this component, please let us know what you found so we can make it better for everyone. There is an open discussion on GitHub where you can share anything you think might be useful.
Discuss Horizontal navigation on GitHub
Get in touch
If you’ve got a question, idea or suggestion email the Design System team on dwp-design-system@engineering.digital.dwp.gov.uk