Components

Primary navigation

Status: To be reviewed

Created in June 2021.

How ‘to be reviewed’ components work

Components with a ‘to be reviewed’ status have been added for use by everyone, but have not been checked or improved recently. Read about all the Design System statuses.

Open this example in a new window

<div class="moj-primary-navigation">

  <div class="moj-primary-navigation__container">

    <div class="moj-primary-navigation__nav">

      <nav class="moj-primary-navigation" aria-label="Primary navigation">

        <ul class="moj-primary-navigation__list">
          <li class="moj-primary-navigation__item">
            <a class="moj-primary-navigation__link" aria-current="page" href="#1">Nav item 1</a>
          </li>

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

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

      </nav>

    </div>
  </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.
searchHtml	sting	No
containerClasses	string	No	Classes to add to the parent `div` container.
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.

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/primary-navigation/macro.njk" import mojPrimaryNavigation -%}

{{ mojPrimaryNavigation({
  label: "Primary navigation",
  items: [
    {
      text: "Nav item 1",
      href: "#1",
      active: true
    },
    {
      text: "Nav item 2",
      href: "#2"
    },
    {
      text: "Nav item 3",
      href: "#3"
    }
  ]
}) }}

When to use

Use the primary navigation component to let users navigate and search your service.

How to use

You must use this component with the header component.

Links

You must only include links to top level sections within your service.

Do not put calls to action in the primary navigation. For example, ‘Create case’ should be an action from within the ‘cases’ section and not a link inside the primary navigation.

Inline search

If your service can search anything, use an inline search form.

Open this example in a new window

HTML (Primary navigation with inline search (example))
Nunjucks (Primary navigation with inline search (example))

<div class="moj-primary-navigation">

  <div class="moj-primary-navigation__container">

    <div class="moj-primary-navigation__nav">

      <nav class="moj-primary-navigation" aria-label="Primary navigation">

        <ul class="moj-primary-navigation__list">
          <li class="moj-primary-navigation__item">
            <a class="moj-primary-navigation__link" aria-current="page" href="#1">Nav item 1</a>
          </li>

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

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

      </nav>

    </div>
    <div class="moj-primary-navigation__search">

      <div class="moj-search moj-search--ondark moj-search--inline">
        <form action="" method="get">

          <div class="govuk-form-group">
            <label class="govuk-label moj-search__label govuk-visually-hidden" for="search-1">
              Search
            </label>

            <input class="govuk-input moj-search__input " id="search-1" name="search-1" type="search">

          </div>

          <button type="submit" class="govuk-button moj-search__button " data-module="govuk-button">
            Search
          </button>

        </form>
      </div>

    </div>
  </div>

</div>

{%- from "moj/components/primary-navigation/macro.njk" import mojPrimaryNavigation -%}
{%- from "moj/components/search/macro.njk" import mojSearch -%}

{%- set inlineSearchHtml %}
  {{ mojSearch({
    classes: "moj-search--ondark moj-search--inline",
    input: {
      id: "search-1",
      name: "search-1"
    },
    label: {
      text: "Search",
      classes: "govuk-visually-hidden"
    },
    button: {
      text: "Search"
    }
  }) }}
{% endset -%}

{{ mojPrimaryNavigation({
  label: "Primary navigation",
  items: [{
    text: "Nav item 1",
    href: "#1",
    active: true
  }, {
    text: "Nav item 2",
    href: "#2"
  }, {
    text: "Nav item 3",
    href: "#3"
  }],
  searchHtml: inlineSearchHtml
}) }}

Toggle search

If your service can only search for certain things, use a toggle search form.

You must tell users what they are searching for in the form hint text, and how they can search using the data-toggle-button.text attribute.

Open this example in a new window

HTML (Primary navigation with toggleable search (example))
Nunjucks (Primary navigation with toggleable search (example))

<div class="moj-primary-navigation">

  <div class="moj-primary-navigation__container">

    <div class="moj-primary-navigation__nav">

      <nav class="moj-primary-navigation" aria-label="Primary navigation">

        <ul class="moj-primary-navigation__list">
          <li class="moj-primary-navigation__item">
            <a class="moj-primary-navigation__link" aria-current="page" href="#1">Nav item 1</a>
          </li>

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

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

      </nav>

    </div>
    <div class="moj-primary-navigation__search">
      <div class="moj-search-toggle" data-module="moj-search-toggle" data-toggle-button.text="Find case">
        <div class="moj-search-toggle__toggle"></div>
        <div class="moj-search-toggle__search">

          <div class="moj-search moj-search--ondark moj-search--toggle moj-js-hidden">

            <form action="" method="get">

              <div class="govuk-form-group">
                <label class="govuk-label moj-search__label govuk-visually-hidden" for="search2">
                  Search
                </label>

                <div id="search2-hint" class="govuk-hint moj-search__hint ">
                  Enter case number, for example 123456
                </div>

                <input class="govuk-input moj-search__input " id="search2" name="search2" type="search" aria-describedby="search2-hint">

              </div>

              <button type="submit" class="govuk-button moj-search__button " data-module="govuk-button">
                Search
              </button>

            </form>
          </div>

        </div>
      </div>
    </div>
  </div>

</div>

{%- from "moj/components/primary-navigation/macro.njk" import mojPrimaryNavigation -%}
{%- from "moj/components/search/macro.njk" import mojSearch -%}

{%- set toggleSearchHtml %}
  <div class="moj-search-toggle" data-module="moj-search-toggle" data-toggle-button.text="Find case">
    <div class="moj-search-toggle__toggle"></div>
    <div class="moj-search-toggle__search">
      {{ mojSearch({
        classes: "moj-search--ondark moj-search--toggle moj-js-hidden",
        input: {
          id: "search2",
          name: "search2"
        },
        label: {
          classes: "govuk-visually-hidden",
          text: "Search"
        },
        hint: {
          text: "Enter case number, for example 123456"
        },
        button: {
          text: "Search"
        }
      }) }}
    </div>
  </div>
{% endset -%}

{{ mojPrimaryNavigation({
  label: "Primary navigation",
  items: [
    {
      text: "Nav item 1",
      href: "#1",
      active: true
    },
    {
      text: "Nav item 2",
      href: "#2"
    },
    {
      text: "Nav item 3",
      href: "#3"
    }
  ],
  searchHtml: toggleSearchHtml
}) }}

Get help and contribute

Get help

You can contact the MoJ Design System team for help or support using this component.

Help improve this component

The MoJ Design System team would like to hear:

how you have used this component in your service
any feedback you have about its usage, for example accessibility or ideas for improvement

Add these comments to the primary navigation discussion on GitHub.

Cookies on MoJ Design System

Primary navigation

Container

Items

When to use

How to use

Links

Inline search

Toggle search

Get help and contribute

Get help

Help improve this component