Components Side navigation

Last updated: 25 January 2024

<div class="govuk-grid-row">

  <div class="govuk-grid-column-one-third">

    <nav class="moj-side-navigation" aria-label="Side navigation">
      <ul class="moj-side-navigation__list">
        <li class="moj-side-navigation__item moj-side-navigation__item--active">
          <a href="#1" aria-current="location">Nav item 1</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#2">Nav item 2</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#3">Nav item 3</a>
        </li>
      </ul>
    </nav>

  </div>

</div>

Nunjucks macro options

Container

Name Type Required Description
label string No The aria-label to add to the navigation container.
items array Yes An array of navigation item objects. See items.
sections array No An array of navigation section objects. See sections.
classes string No Classes to add to the nav container.
attributes object No HTML attributes (for example data attributes) to add to the nav container.

Sections

Name Type Required Description
items array Yes An array of navigation item objects. See items.
heading object Yes See heading

Headings

Name Type Required Description
headingLevel numeric No A number for the heading level. Defaults to 4 (<h4>)
text string Yes If html is set, this is not required. Text to use within the heading. If html is provided, the text argument will be ignored.
html string Yes If text is set, this is not required. HTML to use within the heading. If html is provided, the text argument will be ignored.
classes string No Classes to add to the heading.
attributes object No HTML attributes (for example data attributes) to add to the navigation item anchor.

Items

Name Type Required Description
href string Yes URL of the navigation item anchor. Both href and text attributes for navigation items need to be provided to create an item.
text string Yes If html is set, this is not required. Text to use within the anchor. If html is provided, the text argument will be ignored.
html string Yes If text is set, this is not required. HTML to use within the anchor. If html is provided, the text argument will be ignored.
active boolean No Flag to mark the navigation item as active or not. Defaults to false.
attributes object No HTML attributes (for example data attributes) to add to the navigation item anchor.

Warning: If you’re using Nunjucks macros in production be aware that using HTML arguments, or ones ending with .html can be at risk from cross-site scripting attacks. More information about security vulnerabilities can be found in the Nunjucks documentation.

{%- from "moj/components/side-navigation/macro.njk" import mojSideNavigation -%}

<div class="govuk-grid-row">

  <div class="govuk-grid-column-one-third">

    {{ mojSideNavigation({
      label: 'Side navigation',
      items: [{
        text: 'Nav item 1',
        href: '#1',
        active: true
      }, {
        text: 'Nav item 2',
        href: '#2'
      }, {
        text: 'Nav item 3',
        href: '#3'
      }]
    }) }}

  </div>

</div>

To use the component in your design, add the MoJ Figma Kit to your Figma libraries and find the component using the Assets tab.

View component in MoJ Figma Kit

When to use

Use the side navigation component to let users navigate sub sections in a system or service.

Use this component when you have a second level of navigation. See also the sub navigation component

When not to use

Do not use this component for primary level items or global navigation items.

How to use

The component can be configured to group navigation items into sections

Sections

<div class="govuk-grid-row">

  <div class="govuk-grid-column-one-third">

    <nav class="moj-side-navigation" aria-label="Side navigation">
      <h4 class="moj-side-navigation__title">Section 1</h4>
      <ul class="moj-side-navigation__list">
        <li class="moj-side-navigation__item moj-side-navigation__item--active">
          <a href="#1.1" aria-current="location">Nav item 1.1</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#1.2">Nav item 1.2</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#1.3">Nav item 1.3</a>
        </li>
      </ul>

      <h4 class="moj-side-navigation__title">Section 2</h4>
      <ul class="moj-side-navigation__list">
        <li class="moj-side-navigation__item">
          <a href="#2.1">Nav item 2.1</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#2.2">Nav item 2.2</a>
        </li>

        <li class="moj-side-navigation__item">
          <a href="#2.3">Nav item 2.3</a>
        </li>
      </ul>
    </nav>

  </div>

</div>

Nunjucks macro options

Container

Name Type Required Description
label string No The aria-label to add to the navigation container.
items array Yes An array of navigation item objects. See items.
sections array No An array of navigation section objects. See sections.
classes string No Classes to add to the nav container.
attributes object No HTML attributes (for example data attributes) to add to the nav container.

Sections

Name Type Required Description
items array Yes An array of navigation item objects. See items.
heading object Yes See heading

Headings

Name Type Required Description
headingLevel numeric No A number for the heading level. Defaults to 4 (<h4>)
text string Yes If html is set, this is not required. Text to use within the heading. If html is provided, the text argument will be ignored.
html string Yes If text is set, this is not required. HTML to use within the heading. If html is provided, the text argument will be ignored.
classes string No Classes to add to the heading.
attributes object No HTML attributes (for example data attributes) to add to the navigation item anchor.

Items

Name Type Required Description
href string Yes URL of the navigation item anchor. Both href and text attributes for navigation items need to be provided to create an item.
text string Yes If html is set, this is not required. Text to use within the anchor. If html is provided, the text argument will be ignored.
html string Yes If text is set, this is not required. HTML to use within the anchor. If html is provided, the text argument will be ignored.
active boolean No Flag to mark the navigation item as active or not. Defaults to false.
attributes object No HTML attributes (for example data attributes) to add to the navigation item anchor.

Warning: If you’re using Nunjucks macros in production be aware that using HTML arguments, or ones ending with .html can be at risk from cross-site scripting attacks. More information about security vulnerabilities can be found in the Nunjucks documentation.

{%- from "moj/components/side-navigation/macro.njk" import mojSideNavigation -%}

<div class="govuk-grid-row">

  <div class="govuk-grid-column-one-third">

    {{ mojSideNavigation({
      label: 'Side navigation',
      sections: [
        {
          heading: {
            text: 'Section 1'
          },
          items: [{
            text: 'Nav item 1.1',
            href: '#1.1',
            active: true
          }, {
            text: 'Nav item 1.2',
            href: '#1.2'
          }, {
            text: 'Nav item 1.3',
            href: '#1.3'
          }]
        },
        {
          heading: {
            text: 'Section 2'
          },
          items: [{
            text: 'Nav item 2.1',
            href: '#2.1'
          }, {
            text: 'Nav item 2.2',
            href: '#2.2'
          }, {
            text: 'Nav item 2.3',
            href: '#2.3'
          }]
        }
      ]
    }) }}

  </div>

</div>

Accessibility issues

By default, the section headings use the H4 heading size. This can create an illogical structure if higher heading levels are missing from the page. For some assistive technology users that navigate using heading structures this may cause difficulties.

When viewed on smaller screens and when there are more than three links, users will have to scroll horizontally as well as vertically to see all the content. This has been raised in an external audit under Web Content Accessibility Guidelines (WCAG) 1.4.10 Reflow (Level AA). If you use this component without addressing this issue, you must list it in the accessibility statement.