A-Z
Accordion
Action
Alert
Breadcrumbs
- When to use this component
- When not to use this component
- How it works
- Status of development
Button
Card
Checkboxes
Cookie banner
Date input
Details
Filter
Footer
Forms
Group
Help
Hero
Horizontal rule
Leave site
Notification
Pagination
Progress
Radios
Select
Signage
Skip link
Status
Steps
Summary list
Table
Tabs
Text input
Textarea
Time input

Breadcrumbs

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

Preview
HTML
Nunjucks
Twig
365

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 "components/breadcrumbs/macro.njk" import aspBreadcrumbs %}

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

Twig 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 "asp-frontend/components/breadcrumbs/macro.njk" import aspBreadcrumbs %}

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

Name	Type	Description
PaddingWidth	number	Required. This is used to determine the gaps to the left and right of this component. This should be set using varPaddingWidth which will dynamically update with the app size.
StepsCount	number	Required. The number of screens/steps to be included in the breadcrumb component. This ensures that the last is not a bold/hyperlink style, but previous steps are.
Step1Text	string	Required. Text input for the text to be shown for step 1.
Step2Text	string	Required. Text input for the text to be shown for step 2.
Step3Text	string	Required. Text input for the text to be shown for step 3.
Step4Text	string	Required. Text input for the text to be shown for step 4.
Step1Screen	string	Required. Screen input for the screen to navigate to from step 1.
Step2Screen	string	Required. Screen input for the screen to navigate to from step 2.
Step3Screen	string	Required. Screen input for the screen to navigate to from step 3.
Step4Screen	string	Required. Screen input for the screen to navigate to from step 4.
Step1Width	number	Required. Number input for the width of the text for step 1 (only applies if it’s the last step).
Step1BoldWidth	number	Required. Number input for the width of the text for step 1 (only applies if it’s not the last step and is bold/hyperlinked).
Step2Width	number	Required. Number input for the width of the text for step 2 (only applies if it’s the last step).
Step2BoldWidth	number	Required. Number input for the width of the text for step 2 (only applies if it’s not the last step and is bold/hyperlinked).
Step3Width	number	Required. Number input for the width of the text for step 3 (only applies if it’s the last step).
Step3BoldWidth	number	Required. Number input for the width of the text for step 3 (only applies if it’s not the last step and is bold/hyperlinked).
Step4Width	number	Required. Number input for the width of the text for step 4 (only applies if it’s the last step).
Step4BoldWidth	number	Required. Number input for the width of the text for step 4 (only applies if it’s not the last step and is bold/hyperlinked).
Font	string	Required. This is the font that the text will be shown in. This will likely be Font.'Segoe UI'.
DarkMode	boolean	Required. Input to determine if the component should be dark mode or not. Set by named formula variable varDarkMode.

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	Completed
Documentation	In progress

Published 3 May 2024
Last updated 4 March 2025