Alpha

This is an alpha release of our documentation site. View the roadmap.

Breadcrumbs

On this page

Breadcrumbs

Breadcrumbs show users the current location on the website and enable them to quickly move up to a parent level.

When to use

Use breadcrumbs when a page is located in a hierarchy of at least two levels.

When not to use

Do not use breadcrumbs on a website with a flat hierarchy or to show the journey through a transaction. If a page is taking users through a multistep process, use the “Step-by-step Sidebar Navigation” (or consider if a progress indicator is needed) instead.

How it works

Breadcrumbs should be placed on the top left of each page and below the global navigation. They should start with a link to the home page and end with the current page title. Page titles of parent pages should be linked; the current should not have a link. Note that you will have to add the ‘Home’ link into the links you pass in.

On the small breakpoint, breadcrumbs show the previous parent level as a link by default. You can explicity set this behaviour by passing in collaspe as the type.

Note: the breadcrumbs component on the small breakpoint is currently experimental because more research is needed to validate it.

Accessibility

Keyboard

Users should be able to tab between all links using their keyboard.

Screen reader

Make sure your breadcrumb items reflect the page titles exactly for screen readers.

Site level breadcrumbs

When breadcrumbs are displayed across the top of site content they must be wrapped in a .cads-breadcrumb-wrapper, this will correctly style and align the breadcrumbs with site content. See sample pages for details.

NB: If you are using the ViewComponent version of the breadcrumbs, they will be wrapped for you by default. You can pass full_width: false if you don’t want those crumbs wrapped.

Open example in a new tab 
<div class="cads-breadcrumbs-wrapper">
  <nav class="cads-breadcrumbs cads-breadcrumbs--collapse" aria-label="breadcrumbs">
    <ul class="cads-breadcrumbs__list">
      <li class="cads-breadcrumbs__crumb">
        <a href="/" class="cads-breadcrumb">Home</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/immigration" class="cads-breadcrumb">Immigration</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <span class="cads-breadcrumb" aria-current="location">Staying in the UK</span>
      </li>
    </ul>
  </nav>
</div>
<%= render (
    CitizensAdviceComponents::Breadcrumbs.new(
      type: :collapse,
      links: [
        {
          title: "Home",
          url: "/"
        },
        {
          title: "Immigration",
          url: "/immigration"
        },
        {
          title: "Staying in the UK"
        }
      ]
    )
)
%>

Variations

No collapse

To prevent the default collapse behaviour on the small breakpoint, pass "type" => "no-collapse". For example: in search results.

Open example in a new tab 
<div class="cads-breadcrumbs-wrapper">
  <nav class="cads-breadcrumbs cads-breadcrumbs--no-collapse" aria-label="breadcrumbs">
    <ul class="cads-breadcrumbs__list">
      <li class="cads-breadcrumbs__crumb">
        <a href="/" class="cads-breadcrumb">Home</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/immigration" class="cads-breadcrumb">Immigration</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <span class="cads-breadcrumb" aria-current="location">Staying in the UK</span>
      </li>
    </ul>
  </nav>
</div>
<%= render (
    CitizensAdviceComponents::Breadcrumbs.new(
      type: :no_collapse,
      links: [
        {
          title: "Home",
          url: "/"
        },
        {
          title: "Immigration",
          url: "/immigration"
        },
        {
          title: "Staying in the UK"
        }
      ]
    )
)
%>

Long page titles in breadcrumbs

This story shows how longer breadcrumb titles are displayed.

Open example in a new tab 
<div class="cads-breadcrumbs-wrapper">
  <nav class="cads-breadcrumbs cads-breadcrumbs--collapse" aria-label="breadcrumbs">
    <ul class="cads-breadcrumbs__list">
      <li class="cads-breadcrumbs__crumb">
        <a href="/" class="cads-breadcrumb">Home</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/immigration" class="cads-breadcrumb">My Grandmother Asked Me to Tell You She’s Sorry</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/immigration/staying-in-the-uk" class="cads-breadcrumb">The Curious Incident of the Dog in the Night-Time</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/" class="cads-breadcrumb">Fried Green Tomatoes at the Whistle Stop Cafe</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <span class="cads-breadcrumb" aria-current="location">Eleanor Oliphant is Completely Fine</span>
      </li>
    </ul>
  </nav>
</div>
<%= render(
      CitizensAdviceComponents::Breadcrumbs.new(
        type: :collapse,
        links: [
          {
            title: "Home",
            url: "/"
          },
          {
            title: "My Grandmother Asked Me to Tell You She’s Sorry",
            url: "/immigration"
          },
          {
            title: "The Curious Incident of the Dog in the Night-Time",
            url: "/immigration/staying-in-the-uk"
          },
          {
            title: "Fried Green Tomatoes at the Whistle Stop Cafe",
            url: "/"
          },
          {
            title: "Eleanor Oliphant is Completely Fine"
          }
        ]
      )
    )
%>

Not full width

When shown somewhere where they should not be full width, as in a search result, you can pass in full_width: false. This will prevent the default wrapping behaviour mentioned above.

Open example in a new tab 
<nav class="cads-breadcrumbs cads-breadcrumbs--no-collapse" aria-label="breadcrumbs">
  <ul class="cads-breadcrumbs__list">
    <li class="cads-breadcrumbs__crumb">
      <a href="/" class="cads-breadcrumb">Home</a>
    </li>
    <li class="cads-breadcrumbs__crumb">
      <a href="/immigration" class="cads-breadcrumb">My Grandmother Asked Me to Tell You She’s Sorry</a>
    </li>
    <li class="cads-breadcrumbs__crumb">
      <a href="/immigration/staying-in-the-uk" class="cads-breadcrumb">The Curious Incident of the Dog in the Night-Time</a>
    </li>
    <li class="cads-breadcrumbs__crumb">
      <a href="/" class="cads-breadcrumb">Fried Green Tomatoes at the Whistle Stop Cafe</a>
    </li>
    <li class="cads-breadcrumbs__crumb">
      <span class="cads-breadcrumb" aria-current="location">Eleanor Oliphant is Completely Fine</span>
    </li>
  </ul>
</nav>
<%= render(
      CitizensAdviceComponents::Breadcrumbs.new(
        type: :no_collapse,
        full_width: false,
        links: [
          {
            title: "Home",
            url: "/"
          },
          {
            title: "My Grandmother Asked Me to Tell You She’s Sorry",
            url: "/immigration"
          },
          {
            title: "The Curious Incident of the Dog in the Night-Time",
            url: "/immigration/staying-in-the-uk"
          },
          {
            title: "Fried Green Tomatoes at the Whistle Stop Cafe",
            url: "/"
          },
          {
            title: "Eleanor Oliphant is Completely Fine"
          }
        ]
      )
    )
%>

Not indicating the current page

If you do not want the last crumb to indicate the current page (for screen readers etc), you can pass in current_page: false.

Open example in a new tab 
<div class="cads-breadcrumbs-wrapper">
  <nav class="cads-breadcrumbs cads-breadcrumbs--no-collapse" aria-label="breadcrumbs">
    <ul class="cads-breadcrumbs__list">
      <li class="cads-breadcrumbs__crumb">
        <a href="/" class="cads-breadcrumb">Home</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <a href="/immigration" class="cads-breadcrumb">Immigration</a>
      </li>
      <li class="cads-breadcrumbs__crumb">
        <span class="cads-breadcrumb">Staying in the UK</span>
      </li>
    </ul>
  </nav>
</div>
<%= render ( 
  CitizensAdviceComponents::Breadcrumbs.new(
      type: :no_collapse,
      current_page: false,
      links: [
        {
          title: "Home",
          url: "/"
        },
        {
          title: "Immigration",
          url: "/immigration"
        },
        {
          title: "Staying in the UK"
        }
      ]
    )
  )
%>

Using with Rails

If you are using the citizens_advice_components gem, you can call the component from within a template using:

<%= render (
    CitizensAdviceComponents::Breadcrumbs.new(
      type: :collapse,
      links: [
        {
          title: "Home",
          url: "/"
        },
        {
          title: "Immigration",
          url: "/immigration"
        },
        {
          title: "Staying in the UK"
        }
      ]
    )
)
%>

Component arguments

Argument Description
Argument links Description Required, an array of hashes, each with the following
Argument link[url] Description → Required, url for the breadcrumb link
Argument link[title] Description → Required, title for the breadcrumb link
Argument type Description Optional, one of :collapse (default), :no_collapse
Argument current_page Description Optional, will render aria-location=current on last crumb if true. Defaults to true.
Argument full_width Description Optional, will wrap breadcrumbs in the .cads-breadcrumbs-wrapper div if true. Defaults to true.