Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Breadcrumbs

Overview

Use breadcrumbs to display a list of links to the parent pages of the current page in hierarchical order.

Breadcrumbs help users find their place within a website or web application.

Open this example in a new tab (Example Breadcrumbs)

Example Breadcrumbs contents

Nunjucks

{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}

{{
    onsBreadcrumbs({
        "ariaLabel": 'Breadcrumbs',
        "itemsList": [
            {
                "url": '/',
                "text": 'Home'
            },
            {
                "url": '/components',
                "text": 'Components'
            }
        ]
    })
}}

Nunjucks macro options

NameTypeRequiredDescription
classesstringfalseCustom classes to add to the breadcrumbs nav element
ariaLabelstringfalseThe aria-label added to the nav element. Defaults to “Breadcrumbs”.
idstringfalseThe id added to the nav element
itemsListArray<BreadcrumbsItem>trueAn array of breadcrumb items
BreadcrumbsItem
NameTypeRequiredDescription
itemClassesstringfalseCustom classes to add to the breadcrumbs list item
linkClassesstringfalseCustom classes to add to the breadcrumb link
idstringfalseThe ID added to the breadcrumb link
urlstringtrueThe URL for the breadcrumb link
textstringtrueThe title of the page the breadcrumb is linking to
attributesobjectfalseHTML attributes (for example, data attributes) to add to the breadcrumb link

HTML

<nav class="ons-breadcrumbs" aria-label="Breadcrumbs">
  <ol class="ons-breadcrumbs__items ons-u-fs-s">
    <li class="ons-breadcrumbs__item" id="breadcrumb-1">
      <a class="ons-breadcrumbs__link" href="/">Home</a><svg class="ons-icon" viewBox="0 0 8 13"
        xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg>
    </li>
    <li class="ons-breadcrumbs__item" id="breadcrumb-2">
      <a class="ons-breadcrumbs__link" href="/components">Components</a><svg class="ons-icon" viewBox="0 0 8 13"
        xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg>
    </li>
  </ol>
</nav>

When not to use this component

Do not use the breadcrumbs component on websites with a flat structure.

To help users navigate back through a linear journey or transaction, use a back link.

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

How to use this component

Always place back links before a page’s <main> content element.

This allows them to be skipped with the skip to content component.

To ensure the component is placed correctly set breadcrumbs in the pageConfig of the base page template.

How it works

The set of links is structured using a <ul> to provide semantic structure.

Landmarks

A <nav> element labelled “Breadcrumbs” identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it is easy to locate.

Separators

To prevent screen readers announcing the visual separators between links, they are added via CSS.

The separators are part of the visual presentation that signifies the breadcrumb trail.

This is already semantically represented by the <nav> element with its aria-label of “Breadcrumbs”. Therefore, using a display technique that is not used by screen readers prevents unnecessary distraction.

Variants

Single breadcrumb

When the component only has a single breadcrumb it will display like this.

Open this example in a new tab (Example Breadcrumbs Single)

Example Breadcrumbs Single contents

Nunjucks
{% from "components/breadcrumbs/_macro.njk" import onsBreadcrumbs %}

{{
    onsBreadcrumbs({
        "ariaLabel": 'Breadcrumbs',
        "itemsList": [
            {
                "url": '/',
                "text": 'Home'
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
classesstringfalseCustom classes to add to the breadcrumbs nav element
ariaLabelstringfalseThe aria-label added to the nav element. Defaults to “Breadcrumbs”.
idstringfalseThe id added to the nav element
itemsListArray<BreadcrumbsItem>trueAn array of breadcrumb items
BreadcrumbsItem
NameTypeRequiredDescription
itemClassesstringfalseCustom classes to add to the breadcrumbs list item
linkClassesstringfalseCustom classes to add to the breadcrumb link
idstringfalseThe ID added to the breadcrumb link
urlstringtrueThe URL for the breadcrumb link
textstringtrueThe title of the page the breadcrumb is linking to
attributesobjectfalseHTML attributes (for example, data attributes) to add to the breadcrumb link
HTML
<nav class="ons-breadcrumbs" aria-label="Breadcrumbs">
  <ol class="ons-breadcrumbs__items ons-u-fs-s">
    <li class="ons-breadcrumbs__item" id="breadcrumb-1">
      <a class="ons-breadcrumbs__link" href="/">Home</a><svg class="ons-icon" viewBox="0 0 8 13"
        xmlns="http://www.w3.org/2000/svg" focusable="false" fill="currentColor" role="img" title="ons-icon-chevron">
        <path
          d="M5.74,14.28l-.57-.56a.5.5,0,0,1,0-.71h0l5-5-5-5a.5.5,0,0,1,0-.71h0l.57-.56a.5.5,0,0,1,.71,0h0l5.93,5.93a.5.5,0,0,1,0,.7L6.45,14.28a.5.5,0,0,1-.71,0Z"
          transform="translate(-5.02 -1.59)" />
      </svg>
    </li>
  </ol>
</nav>

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Breadcrumbs’ component on GitHub (opens in a new tab)