Navigation - Breadcrumbs

Use breadcrumbs to help users understand where they are in the website.

WCAG 2.2

WCAG 2.2 affects this component

To meet new success criteria introduced in the Web Content Accessibility Guidelines (WCAG) 2.2, make sure that users can successfully:

See the full list of design system changes to meet WCAG 2.2.

Open this default breadcrumbs example in new window
Copy default breadcrumbs code 
<nav class="nhsuk-breadcrumb" aria-label="Breadcrumb">
  <div class="nhsuk-width-container">
    <ol class="nhsuk-breadcrumb__list">
      <li class="nhsuk-breadcrumb__item"><a class="nhsuk-breadcrumb__link" href="/level-one">Level one</a></li>
      <li class="nhsuk-breadcrumb__item"><a class="nhsuk-breadcrumb__link" href="/level-one/level-two">Level two</a></li>

      <li class="nhsuk-breadcrumb__item"><a class="nhsuk-breadcrumb__link" href="/level-one/level-two/level-three">Level three</a></li>

    </ol>
    <p class="nhsuk-breadcrumb__back">
      <a class="nhsuk-breadcrumb__backlink" href="/level-one/level-two/level-three">
        <span class="nhsuk-u-visually-hidden">Back to &nbsp;</span>
        Level three
      </a>
    </p>
  </div>
</nav>
Close default breadcrumbs code
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.

Nunjucks arguments for default breadcrumbs
Name Type Required Description
Name items Type array Required true Description Array of breadcrumbs item objects.
Name items[].text Type string Required true Description Text to use within the breadcrumbs item.
Name items[].href Type string Required false Description The value of the breadcrumb item link href attribute.
Name items[].attributes Type object Required false Description HTML attributes (for example data attributes) to add to the individual crumb.
Name text Type string Required true Description Text to use for the current page.
Name href Type string Required true Description The value of the current page link href attribute.
Name classes Type string Required false Description Classes to add to the container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the container.
Copy default breadcrumbs code 
{% from 'breadcrumb/macro.njk' import breadcrumb %}

{{ breadcrumb({
  items: [
    {
      href: "/level-one",
      text: "Level one"
    },
    {
      href: "/level-one/level-two",
      text: "Level two"
    }
  ],
  href: "/level-one/level-two/level-three",
  text: "Level three"
}) }}
Close default breadcrumbs code

When to use breadcrumbs

Use breadcrumbs to give users context and let them move back or up a level if they can't find what they want on the page.

When not to use breadcrumbs

Don't use breadcrumbs in transactional journeys as they can get in the way of the user completing the task.

How to use breadcrumbs

If the full breadcrumb trail doesn't fit the screen size, it can wrap onto 2 lines, but don't break a breadcrumb if it doesn't fit the line.

Information: WCAG 2.2

Make sure no other interactive elements are too close to the breadcrumbs. This is to make sure users can easily interact with the breadcrumbs. This is to comply with WCAG 2.2 success criterion 2.5.8 Target Size (W3C).

You don't need to show the current page in the breadcrumb because this information is in the H1.

On mobile, we replace the full breadcrumb trail with a "Back to [parent]" link.

Accessibility

We use aria-label="breadcrumb" as a label in the nav element to let people who use screen readers know what it is.

We add aria-hidden="true" to the svg icons to hide them from people who use screen readers.

Research

We tested breadcrumbs on pages with lots of content about conditions or medicines. They helped people understand their place on the website. People noticed them and appreciated the context they gave. People also used them to get back to where they came from or to get back home.

We took out the breadcrumb links when we tested our pages in transactional journeys (in more than 3 labs). We thought that having extra links would distract users and that fewer people would complete the journey. As we expected, we found that users didn't miss the links because they were focused on the task.

Help us improve this guidance

Share insights or feedback and take part in the discussion. We use GitHub as a collaboration space. All the information on it is open to the public.

Feedback or share insights on GitHub

Read more about how to feedback or share insights.

If you have any questions, get in touch with the service manual team.

Updated: April 2024