Breadcrumb

Breadcrumb navigation marks the current page's location in a site hierarchy and links to ancestor pages.

@layer components

Introduction

The .breadcrumb component renders an ordered list of labels tracing the current page's position in the site hierarchy. Each item either links to an ancestor page or marks the current location. Separators between items are generated automatically from a CSS custom property and require no extra markup.

Basic structure

Wrap an ordered list in .breadcrumb and apply .breadcrumb-item to each <li>. Place aria-current="page" on the last item to identify the current page, and wrap the whole structure in a <nav> element with aria-label="breadcrumb".

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item" aria-current="page">Home</li>
  </ol>
</nav>

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="#">Home</a></li>
    <li class="breadcrumb-item" aria-current="page">Library</li>
  </ol>
</nav>

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="#">Home</a></li>
    <li class="breadcrumb-item"><a href="#">Library</a></li>
    <li class="breadcrumb-item" aria-current="page">Data</li>
  </ol>
</nav>

Separator customization

Separators are inserted by the ::before pseudo-element on each .breadcrumb-item that follows another. The separator character comes from the --cx-breadcrumb-divider CSS custom property, falling back to the compiled value of $breadcrumb-divider. Setting this property at runtime requires no recompilation.

<nav style="--cx-breadcrumb-divider: '>';" aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="#">Home</a></li>
    <li class="breadcrumb-item" aria-current="page">Library</li>
  </ol>
</nav>

To set the separator at compile time, override the Sass variables. Use string.quote() to wrap the character in the quotes that the CSS content property requires.

$breadcrumb-divider:     string.quote(">");

SVG icon separators

An embedded SVG can replace the text character. Apply the icon as an inline data URI via the CSS custom property, or override the Sass variables.

When using SVG icons as separators, characters such as <, >, and # must be URL-encoded. Chassis handles this automatically for Sass variables with the escape-svg() function. When setting the CSS custom property directly in HTML, URL-encode the SVG manually.

<nav aria-label="breadcrumb" style="
    --cx-breadcrumb-divider: url(&#34;data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23888888' width='12' height='12'%3E%3Cpath d='M4.7 2L3.8 2.9 6.9 6l-3.1 3.1.9.9 4-4z'/%3E%3C/svg%3E&#34;);
    --cx-breadcrumb-divider-rtl: url(&#34;data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23888888' width='12' height='12'%3E%3Cpath d='M7.3 2L8.2 2.9 5.1 6l3.1 3.1-.9.9-4-4z'/%3E%3C/svg%3E&#34;);
    ">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="#">Home</a></li>
    <li class="breadcrumb-item" aria-current="page">Library</li>
  </ol>
</nav>

SVG icons do not carry bidi mirroring. Use $breadcrumb-divider-rtl to supply a horizontally flipped path for RTL contexts.

$breadcrumb-divider:     url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='%23888888'><path d='M4.7 2L3.8 2.9 6.9 6l-3.1 3.1.9.9 4-4z' /></svg>");
$breadcrumb-divider-rtl: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='%23888888'><path d='M7.3 2L8.2 2.9 5.1 6l3.1 3.1-.9.9-4-4z' /></svg>");

SVG used via the content property cannot be recolored at runtime. Choose a neutral color within the SVG to maintain sufficient contrast in both light and dark color modes.

Removing separators

Set both the divider value and the divider width to remove separators entirely. Increasing $breadcrumb-gap (or --cx-breadcrumb-gap at runtime) maintains spacing between items when the divider width is zero.

$breadcrumb-divider:       none;
$breadcrumb-divider-width: 0;
$breadcrumb-gap:           1rem;

<nav style="--cx-breadcrumb-divider: ''; --cx-breadcrumb-divider-width: 0; --cx-breadcrumb-gap: 1rem;" aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a href="#">Home</a></li>
    <li class="breadcrumb-item" aria-current="page">Library</li>
  </ol>
</nav>

Accessibility

Wrap the breadcrumb list in a <nav> element with aria-label="breadcrumb" so assistive technologies expose the region as a labeled navigation landmark. Apply aria-current="page" to the last .breadcrumb-item to identify the current page to screen readers without relying on visual styling alone. See the ARIA Authoring Practices Guide breadcrumb pattern for the full specification.

CSS

This component can be customized through Sass variables at compile time.

Custom properties

This component exposes CSS custom properties to control its appearance at runtime.

--cx-padding-y: var(--cx-breadcrumb-padding-y, 0px);
--cx-padding-x: var(--cx-breadcrumb-padding-x, 0px);
--cx-gap: var(--cx-breadcrumb-gap, 0.25rem);
--cx-margin-bottom: var(--cx-breadcrumb-margin-bottom, 1rem);
--cx-font-family: var(--cx-breadcrumb-font-family, var(--cx-font-family-text));
--cx-font-size: var(--cx-breadcrumb-font-size, var(--cx-font-size-text-medium));
--cx-font-weight: var(--cx-breadcrumb-font-weight, var(--cx-font-weight-text-normal));
--cx-line-height: var(--cx-breadcrumb-line-height, var(--cx-line-height-text-medium));
--cx-fg-color: var(--cx-breadcrumb-fg-color, var(--cx-fg-subtle));
--cx-bg-color: var(--cx-breadcrumb-bg-color, initial);
--cx-border-width: var(--cx-breadcrumb-border-width, 0px);
--cx-border-color: var(--cx-breadcrumb-border-color, transparent);
--cx-border-radius: var(--cx-breadcrumb-border-radius, initial);
--cx-link-main-color: var(--cx-breadcrumb-link-main-color, inherit);
--cx-link-hover-color: var(--cx-breadcrumb-link-hover-color, inherit);
--cx-divider-width: var(--cx-breadcrumb-divider-width, 1rem);
--cx-divider-height: var(--cx-breadcrumb-divider-height, 1rem);
--cx-divider-color: var(--cx-breadcrumb-divider-color, var(--cx-fg-subtle));

Sass variables

This component uses Sass variables in scss/config/_defaults.scss to define its defaults.

$breadcrumb-font:               $font-text-medium-normal;
$breadcrumb-padding-y:          0px;
$breadcrumb-padding-x:          0px;
$breadcrumb-gap:                .25rem;
$breadcrumb-margin-bottom:      1rem;
$breadcrumb-border-width:       0px;
$breadcrumb-border-color:       transparent;
$breadcrumb-border-radius:      initial;
$breadcrumb-fg-color:           var(--fg-subtle);
$breadcrumb-bg-color:           initial;

$breadcrumb-divider-width:      1rem;
$breadcrumb-divider-height:     1rem;
$breadcrumb-divider-color:      var(--fg-subtle);
// $breadcrumb-divider:            url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='%23888888'><path d='M4.7 2L3.8 2.9 6.9 6l-3.1 3.1.9.9 4-4z' /></svg>");
$breadcrumb-divider:            string.quote("/");
$breadcrumb-divider-rtl:        $breadcrumb-divider;

$breadcrumb-link-main-color:    inherit;
$breadcrumb-link-hover-color:   inherit;