Components Side navigation

The side navigation component is a list of related links within a service.

Open this side-navigation example in a new tab 
<button class="dwp-side-navigation__button" data-module="dwp-side-navigation"
data-target="dwp-side-navigation-panel"
data-label-hide="Hide navigation"
data-label-show="Show navigation"
aria-expanded="false">
<span class="dwp-side-navigation__section-toggle-focus">
<span class="dwp-side-navigation__chevron dwp-side-navigation__chevron--down"></span>
<span class="dwp-side-navigation__section-toggle-text">Show navigation</span>
</span>
</button>
<nav data-module="dwp-side-navigation-panel" class="dwp-side-navigation dwp-side-navigation--mobile" aria-label="Side" role="navigation">
<ul class="dwp-side-navigation__list">
<li class="dwp-side-navigation__item">
  <a id="d-item-1" href="#d-item-1" class="dwp-side-navigation__link">
    Item 1
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="d-item-2" href="#d-item-2" class="dwp-side-navigation__link">
    Item 2
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="d-item-3" href="#d-item-3" class="dwp-side-navigation__link">
    Item 3
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="d-item-4" href="#d-item-4" class="dwp-side-navigation__link">
    Item 4
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="d-item-5" href="#d-item-5" class="dwp-side-navigation__link">
    Item 5
  </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
selectedSubItem string URL string to highlight selected navigation sub item
ariaLabel string Aria label for navigation, defaults to 'Side Navigation'
mobile object Object of options to control mobile navigation, see mobile

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
subItems array Array of object navigation items, see items subItems

Options for items subItems array object

Name Type Description
text string Required. Value for text of the sub naivigation link
href string Required. Value for the href of the sub navigation link
id string Value for the id of the sub navigation link

Options for mobile object

Name Type Description
disabled boolean toggled if mobile navigation is disabled
showButtonText string Set the initail value of the toggle button, default is "Show navigation"
hideButtonText string Value of the toggle button, default is "Hide navigation" 
{% from "side-navigation/macro.njk" import dwpSideNavigation %}

{{ 
    dwpSideNavigation({
        pageId: "side-navigation-1",
        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"
            },
            {
              text: "Item 4",
              href: "#d-item-4",
              id: "d-item-4"
            },
            {
              text: "Item 5",
              href: "#d-item-5",
              id: "d-item-5"
            }
        ]
    })
}}

When to use this component

Use this component when users need to move around related pages within an area of a service.

The side navigation component is for use in internal services.

When not to use this component

You should not use side navigation as the main navigation in a service. Use the Header navigation component instead.

You should not use this component in public-facing services.

How it works

The side navigation is as a list of links on the left-hand side of the page, below the header and next to the main content. The page the user is on is highlighted in the list. Each link should take the user to different content.

Open this side-navigation example in a new tab 
<button class="dwp-side-navigation__button" data-module="dwp-side-navigation"
data-target="dwp-side-navigation-panel"
data-label-hide="Hide navigation"
data-label-show="Show navigation"
aria-expanded="false">
<span class="dwp-side-navigation__section-toggle-focus">
<span class="dwp-side-navigation__chevron dwp-side-navigation__chevron--down"></span>
<span class="dwp-side-navigation__section-toggle-text">Show navigation</span>
</span>
</button>
<nav data-module="dwp-side-navigation-panel" class="dwp-side-navigation dwp-side-navigation--mobile" aria-label="Side" role="navigation">
<ul class="dwp-side-navigation__list">
<li class="dwp-side-navigation__item">
  <a id="s-item-1" href="#s-item-1" class="dwp-side-navigation__link">
    Item 1
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="s-item-2" href="#s-item-2" class="dwp-side-navigation__link">
    Item 2
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="s-item-3" href="#s-item-3" class="dwp-side-navigation__link">
    Item 3
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="s-item-4" href="#s-item-4" class="dwp-side-navigation__link">
    Item 4
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="s-item-5" href="#s-item-5" class="dwp-side-navigation__link">
    Item 5
  </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
selectedSubItem string URL string to highlight selected navigation sub item
ariaLabel string Aria label for navigation, defaults to 'Side Navigation'
mobile object Object of options to control mobile navigation, see mobile

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
subItems array Array of object navigation items, see items subItems

Options for items subItems array object

Name Type Description
text string Required. Value for text of the sub naivigation link
href string Required. Value for the href of the sub navigation link
id string Value for the id of the sub navigation link

Options for mobile object

Name Type Description
disabled boolean toggled if mobile navigation is disabled
showButtonText string Set the initail value of the toggle button, default is "Show navigation"
hideButtonText string Value of the toggle button, default is "Hide navigation" 
{% from "side-navigation/macro.njk" import dwpSideNavigation %}

{{ 
    dwpSideNavigation({
        pageId: "side-navigation-2",
        selectedItem: "#item-2",
        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"
            },
            {
              text: "Item 4",
              href: "#s-item-4",
              id: "s-item-4"
            },
            {
              text: "Item 5",
              href: "#s-item-5",
              id: "s-item-5"
            }
        ]
    })
}}

Side navigation with child pages

Open this side-navigation example in a new tab 
<nav class="dwp-side-navigation" aria-label="Side" role="navigation">
<ul class="dwp-side-navigation__list">
<li class="dwp-side-navigation__item">
  <a id="sn-item-1" href="#sn-item-1" class="dwp-side-navigation__link">
    Item 1
  </a>
</li>
<li class="dwp-side-navigation__item dwp-side-navigation__item--selected">
  <a id="sn-item-2" href="#sn-item-2" class="dwp-side-navigation__link dwp-side-navigation__link--selected" aria-current="true">
    Item 2
  </a>
  <ul class="dwp-side-navigation__list dwp-side-navigation__list--sub-item">
    <li class="dwp-side-navigation__sub-item">
      <a id="s-sn-item-1" href="#s-sn-item-1" class="dwp-side-navigation__link">
        subitem 1
      </a>
    </li>
    <li class="dwp-side-navigation__sub-item">
      <a id="s-sn-item-2" href="#s-sn-item-2" class="dwp-side-navigation__link">
        subitem 2
      </a>
    </li>
    <li class="dwp-side-navigation__sub-item">
      <a id="s-sn-item-3" href="#s-sn-item-3" class="dwp-side-navigation__link">
        subitem 3
      </a>
    </li>
  </ul>
</li>
<li class="dwp-side-navigation__item">
  <a id="sn-item-3" href="#sn-item-3" class="dwp-side-navigation__link">
    Item 3
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="sn-item-4" href="#sn-item-4" class="dwp-side-navigation__link">
    Item 4
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="sn-item-5" href="#sn-item-5" class="dwp-side-navigation__link">
    Item 5
  </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
selectedSubItem string URL string to highlight selected navigation sub item
ariaLabel string Aria label for navigation, defaults to 'Side Navigation'
mobile object Object of options to control mobile navigation, see mobile

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
subItems array Array of object navigation items, see items subItems

Options for items subItems array object

Name Type Description
text string Required. Value for text of the sub naivigation link
href string Required. Value for the href of the sub navigation link
id string Value for the id of the sub navigation link

Options for mobile object

Name Type Description
disabled boolean toggled if mobile navigation is disabled
showButtonText string Set the initail value of the toggle button, default is "Show navigation"
hideButtonText string Value of the toggle button, default is "Hide navigation" 
{% from "side-navigation/macro.njk" import dwpSideNavigation %}

{{ 
    dwpSideNavigation({
        pageId: "side-navigation-2",
        selectedItem: "#sn-item-2",
        items: [
        {
            text: "Item 1",
            href: "#sn-item-1",
            id: "sn-item-1"
        },
        {
            text: "Item 2",
            href: "#sn-item-2",
            id: "sn-item-2",
            subItems: [
                {
                    text: "subitem 1",
                    href: "#s-sn-item-1",
                    id: "s-sn-item-1"
                },
                {
                    text: "subitem 2",
                    href: "#s-sn-item-2",
                    id: "s-sn-item-2"
                },
                {
                    text: "subitem 3",
                    href: "#s-sn-item-3",
                    id: "s-sn-item-3"
                }
            ]
        },
        {
            text: "Item 3",
            href: "#sn-item-3",
            id: "sn-item-3"
        },
        {
            text: "Item 4",
            href: "#sn-item-4",
            id: "sn-item-4"
        },
        {
            text: "Item 5",
            href: "#sn-item-5",
            id: "sn-item-5"
        }
        ],
        mobile: { 
            disabled: true
        }
    })
}}

Child pages are shown underneath the link section and revealed when a user selects the section. The section is then highlighted and any child pages are indented and preceded by a dash.

Mobile view

Open this side-navigation example in a new tab 
<button class="dwp-side-navigation__button" data-module="dwp-side-navigation"
data-target="dwp-side-navigation-panel"
data-label-hide="Hide navigation"
data-label-show="Show navigation"
aria-expanded="false">
<span class="dwp-side-navigation__section-toggle-focus">
<span class="dwp-side-navigation__chevron dwp-side-navigation__chevron--down"></span>
<span class="dwp-side-navigation__section-toggle-text">Show navigation</span>
</span>
</button>
<nav data-module="dwp-side-navigation-panel" class="dwp-side-navigation dwp-side-navigation--mobile" aria-label="Side" role="navigation">
<ul class="dwp-side-navigation__list">
<li class="dwp-side-navigation__item">
  <a id="m-item-1" href="#m-item-1" class="dwp-side-navigation__link">
    Item 1
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="m-item-2" href="#m-item-2" class="dwp-side-navigation__link">
    Item 2
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="m-item-2" href="#m-item-3" class="dwp-side-navigation__link">
    Item 3
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="m-item-4" href="#m-item-4" class="dwp-side-navigation__link">
    Item 4
  </a>
</li>
<li class="dwp-side-navigation__item">
  <a id="m-item-5" href="#m-item-5" class="dwp-side-navigation__link">
    Item 5
  </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
selectedSubItem string URL string to highlight selected navigation sub item
ariaLabel string Aria label for navigation, defaults to 'Side Navigation'
mobile object Object of options to control mobile navigation, see mobile

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
subItems array Array of object navigation items, see items subItems

Options for items subItems array object

Name Type Description
text string Required. Value for text of the sub naivigation link
href string Required. Value for the href of the sub navigation link
id string Value for the id of the sub navigation link

Options for mobile object

Name Type Description
disabled boolean toggled if mobile navigation is disabled
showButtonText string Set the initail value of the toggle button, default is "Show navigation"
hideButtonText string Value of the toggle button, default is "Hide navigation" 
{% from "side-navigation/macro.njk" import dwpSideNavigation %}

{{ 
    dwpSideNavigation({
        pageId: "side-navigation-1",
        items: [
            {
              text: "Item 1",
              href: "#m-item-1",
              id: "m-item-1"
            },
            {
              text: "Item 2",
              href: "#m-item-2",
              id: "m-item-2"
            },
            {
              text: "Item 3",
              href: "#m-item-3",
              id: "m-item-2"
            },
            {
              text: "Item 4",
              href: "#m-item-4",
              id: "m-item-4"
            },
            {
              text: "Item 5",
              href: "#m-item-5",
              id: "m-item-5"
            }
        ]
    })
}}

On smaller viewports, including mobile, the navigation is displayed as an expandable list that sits at the top of the page, under the service header.

If the user’s device is not using JavaScript

If the user’s device is not running JavaScript the full navigation should always be visible.

Accessibility

On mobile the menu is hidden and revealed using a JavaScript button. This method is used in the GOV.UK Design System Header component.

The font size is 16px at desktop view sizes. This is smaller than the standard size for body text at desktop on an internal service page, which is 19px.

For more about building accessible services see the DWP Accessibility Manual.

Research

This component is being tested in the Health Assessment Service.

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.

For this pattern we’re particularly interested in:

  • how the side navigation works on smaller viewports
  • the stacking of components, for example how users interact with the side navigation when it is used alongside the header, main navigation or key details components

Discuss side 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