Components Header navigation

The header navigation is a version of the internal service header that includes navigation items.

<header data-module="govuk-header" class="dwp-header">
<div class="dwp-header__content govuk-width-container">
<div class="dwp-header__service-name">
  <a href="#" class="dwp-header__link">Service name</a>
</div>
<nav class="dwp-header-navigation"
  aria-label="Primary">
  <button type="button" class="dwp-header-navigation__menu-button govuk-js-header-toggle" aria-controls="navigation" hidden>
    Menu
  </button>
  <ul id="navigation" class="dwp-header-navigation__list">
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Find someone
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Tasks
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Telephone claim
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Paper claim
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Admin
      </a>
    </li>
  </ul>
</nav>
</div>
</header>
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
serviceName string Required. The service name, this replaces the name value
serviceHref string Required. The service url
action string the action of a button
actionHref string The action url
container boolean Whether to use the govuk width container
classes string Additional classes to add to the internal service header
containerClasses string Additional classes to add to the govuk width container
attributes object HTML Attributes (data attributes) to add to the internal service header
navigation object Navigation options for adding navigation to header component, see navigation

Options for navigation object

Name Type Description
attributes object HTML Attributes (data attributes) to add to the internal service header
classes string Additional classes to add to the internal service header
ariaLabel string Sets the description of the navigation, by default this is Primary
selectedItem string URL string to highlight selected navigation item
items array Required. Array of object navigation items, see navigation items
actionItem object This moves the action item to the bottom of navigation for mobile
mobile object Object of options to control mobile navigation, see navigation mobile

Options for navigation 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

Options for navigation mobile object

Name Type Description
disabled boolean Toggle if mobile navigation is disabled
menuButtonText string Sets the label value of the menu button, by default this is Menu
menuButtonAriaLabel string This allows you to give addtional context to the menu button if needed
{% from "internal-service-header/macro.njk" import dwpHeader %}

{{
    dwpHeader({
        serviceName: "Service name",
        serviceHref: '#',
        container: true,
        navigation: {
          items: [
              {
                  href: "#",
                  text: "Find someone"
              },
              {
                  href: "#",
                  text: "Tasks"
              },
              {
                  href: "#",
                  text: "Telephone claim"
              },
              {
                  href: "#",
                  text: "Paper claim"
              },
              {
                  href: "#",
                  text: "Admin"
              }
          ]
      }  
    })
}}

When to use this component

The header navigation component is for internal services. Use this component when your users need to move between key tasks or pages within a service.

If you only need one level of navigation you should use this component. If you also need secondary navigation you can use the side navigation component.

When not to use this component

If your service does not need navigation you should use the standard internal service header component.

If your service is hosted on a [name].service.gov.uk domain it should use the GOV.UK Design System Header component.

You should not use this component to show long lists of navigation. If you have a very long list of navigation items it may be that your service’s information architecture needs to be reviewed.

How it works

The navigation sits inside the internal service header component, left-aligned and below the service name. If the links do not fit on the top line they wrap on to a second line.

Mobile view

On smaller viewports (768px wide or less), including mobile, the main navigation links are listed inside a ‘Menu’ located on the right. The menu uses JavaScript: if JavaScript is not available the full navigation remains visible and links wrap onto new lines as needed.

<header data-module="govuk-header" class="dwp-header">
<div class="dwp-header__content govuk-width-container">
<div class="dwp-header__service-name">
  <a href="#" class="dwp-header__link">Service name</a>
</div>
<nav class="dwp-header-navigation"
  aria-label="Primary">
  <button type="button" class="dwp-header-navigation__menu-button govuk-js-header-toggle" aria-controls="navigation" hidden>
    Menu
  </button>
  <ul id="navigation" class="dwp-header-navigation__list">
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Find someone
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Tasks
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Telephone claim
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Paper claim
      </a>
    </li>
    <li class="dwp-header-navigation__item">
      <a
        href="#">
        Admin
      </a>
    </li>
  </ul>
</nav>
</div>
</header>
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
serviceName string Required. The service name, this replaces the name value
serviceHref string Required. The service url
action string the action of a button
actionHref string The action url
container boolean Whether to use the govuk width container
classes string Additional classes to add to the internal service header
containerClasses string Additional classes to add to the govuk width container
attributes object HTML Attributes (data attributes) to add to the internal service header
navigation object Navigation options for adding navigation to header component, see navigation

Options for navigation object

Name Type Description
attributes object HTML Attributes (data attributes) to add to the internal service header
classes string Additional classes to add to the internal service header
ariaLabel string Sets the description of the navigation, by default this is Primary
selectedItem string URL string to highlight selected navigation item
items array Required. Array of object navigation items, see navigation items
actionItem object This moves the action item to the bottom of navigation for mobile
mobile object Object of options to control mobile navigation, see navigation mobile

Options for navigation 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

Options for navigation mobile object

Name Type Description
disabled boolean Toggle if mobile navigation is disabled
menuButtonText string Sets the label value of the menu button, by default this is Menu
menuButtonAriaLabel string This allows you to give addtional context to the menu button if needed
{% from "internal-service-header/macro.njk" import dwpHeader %}

{{
    dwpHeader({
        serviceName: "Service name",
        serviceHref: '#',
        container: true,
        navigation: {
          items: [
              {
                  href: "#",
                  text: "Find someone"
              },
              {
                  href: "#",
                  text: "Tasks"
              },
              {
                  href: "#",
                  text: "Telephone claim"
              },
              {
                  href: "#",
                  text: "Paper claim"
              },
              {
                  href: "#",
                  text: "Admin"
              }
          ]
      }  
    })
}}

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.

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

Research

This component is based on work carried out by the Winter Fuel Payment and Get your State Pension services.

A citizen-facing service found that some users ignore the navigation when it is placed within the header component. We need more research on this component being used in agent-facing services.

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:

  • banner blindness
  • how the component handles longer lists of navigation

Discuss Header navigation component 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