Components Side navigation

Last updated: 22 May 2020

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

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>