ASP Digital Design System

Breadcrumbs

The breadcrumbs component helps users to understand where they are within a website’s structure and move between levels.

Open this example in a new tab: breadcrumbs

<nav class="asp-breadcrumbs" aria-label="breadcrumbs">
  <div class="container">
    <span class="asp-breadcrumbs__intro">You are here: </span>
    <ol class="asp-breadcrumbs__list">
      <li class="asp-breadcrumbs__item">
        <a class="asp-breadcrumbs__link" href="#/">Home</a>
      </li>
      <li class="asp-breadcrumbs__item">
        <a class="asp-breadcrumbs__link" href="#/#">Link 2</a>
      </li>
      <li class="asp-breadcrumbs__item">
        Current page (not linked)
      </li>
    </ol>
  </div>
</nav>
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
root string Required. The "home" link, the first breadcrumb item.
rows array Required. The breadcrumb items. The last iten will be text without a link. See rows.

Options for rows

Name Type Description
text string Required. The text for the breadcrumb item.
href string or false (boolean) Required. The 'relative' URL for the breadcrumb item. If the item is the last breadcrumb item, the href will be ignored. Default values (for the last breadcrumb item) are false (boolean) or null. 
{% from "breadcrumbs/macro.njk" import aspBreadcrumbs %}


{{ aspBreadcrumbs({
  root: "#",
  rows: [
    {
      text: "Link 2",
      href: "#"
    },
    {
      text: "Current page (not linked)",
      href: "#"
    }
  ]
}) }}

When to use this component

Use the breadcrumbs component when you need to help users understand and move between the multiple levels of a website.

we breadcrumbs are required, ensure that a location-based approach to breadcrumbs is adopted. (rather than attribute-based or path-based).

When not to use this component

Do not use the breadcrumbs component on websites with a flat structure, or to show progress through a linear journey or transaction (such as a form).

If you’re using other navigational elements on the page, such as a sidebar, consider whether your users need the additional support of breadcrumbs.

How it works

Always place breadcrumbs at the top of a page, within the <main> element. Placing them here means that the ‘Skip to main content’ link allows the user to skip all navigation links, including breadcrumbs.

The breadcrumb should start with your ‘home’ page and end with the parent section of the current page.

Status of development

The below criteria all need to be met for a component to be considered as fully developed for use within the ASP Digital Design System.

Development criteria Status
WCAG 2.2 compliant Not started
WCAG 2.1 compliant Completed
HTML / Nunjucks version Completed
Figma version Not started
M365 versions Not started
Documentation In progress

Published 3 May 2024
Last updated 11 September 2024