Breadcrumb

Guide users through your site hierarchy with semantically structured breadcrumb navigation that enhances wayfinding and user orientation.

Introduction

Breadcrumb navigation in Chassis CSS provides a consistent waypoint system to help users understand their current location within your site's hierarchy. This pattern enhances spatial awareness and offers quick navigation paths to parent pages, improving overall user experience and reducing the likelihood of disorientation.

Basic implementation

Create breadcrumb navigation using an ordered list with the .breadcrumb class, adding .breadcrumb-page for each navigation level. The active page should include the active class and appropriate ARIA attributes.

html

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

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

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

Separator customization

Breadcrumb separators in Chassis are implemented through CSS ::before pseudo-elements and design tokens, maintaining consistency with your design system while allowing for flexible customization. You can change separators without recompiling code by modifying the --cx-breadcrumb-divider CSS variable.

html

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

When modifying via Sass, the quote function is required to generate the quotes around a string. For example, using > as the divider, you can use this:

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

SVG icon separators

It's also possible to use an embedded SVG icon. Apply it via CSS custom property, or use the Sass variable.

SVG integration: When using SVG icons as separators, special characters such as <, >, and # must be properly URL-encoded. Chassis handles this automatically for Sass variables using our escape-svg() function. When setting CSS variables directly in HTML or JavaScript, you'll need to handle URL encoding manually.

html

<nav style="--cx-breadcrumb-divider: url(&#34;data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' fill='%23888888' width='8' height='8'%3E%3Cpath d='M2.5 0L1 1.5 3.5 4 1 6.5 2.5 8l4-4-4-4z'/%3E%3C/svg%3E&#34;);" aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-page"><a href="#">Home</a></li>
    <li class="breadcrumb-page active" aria-current="page">Library</li>
  </ol>
</nav>

$breadcrumb-divider: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' fill='#{$breadcrumb-divider-color}' width='8' height='8'><path d='M2.5 0L1 1.5 3.5 4 1 6.5 2.5 8l4-4-4-4z'/></svg>");

Color considerations: When using SVG icons as separators through the content property of the ::before pseudo-element, the color cannot be dynamically changed after rendering. Choose a neutral color value directly within the SVG code to ensure sufficient contrast across both light and dark color modes.

Removing separators

For designs that don't require visible separators, you can remove them entirely:

// In Sass
$breadcrumb-divider: none;

// Or with CSS variables
--cx-breadcrumb-divider: '';

This flexibility allows you to adapt breadcrumb navigation to various design needs while maintaining consistent structure.

html

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

$breadcrumb-divider: none;

Accessibility

For accessible breadcrumbs, use the <nav> element with aria-label="breadcrumb" and apply aria-current="page" to the active item. See the ARIA Authoring Practices Guide for details.

CSS

This component can be customized using CSS variables, allowing for styles to be modified dynamically on the page. These CSS variables are part of Chassis CSS's design token system, giving design teams control over component appearance. See the design tokens page for more details.

Custom properties

These CSS variables control the component's appearance and can be modified dynamically on the page. Components use cascading variables, allowing seamless variations in size, color, and style without redundant style declarations through component inheritance and the context class system.

scss/_breadcrumb.scss

--#{$prefix}padding-y: var(--#{$prefix}breadcrumb-padding-y, #{$breadcrumb-padding-y});
--#{$prefix}padding-x: var(--#{$prefix}breadcrumb-padding-x, #{$breadcrumb-padding-x});
--#{$prefix}margin-bottom: var(--#{$prefix}breadcrumb-margin-bottom, #{$breadcrumb-margin-bottom});
@include map-font($breadcrumb-font, breadcrumb);
--#{$prefix}fg-color: var(--#{$prefix}breadcrumb-fg-color, #{$breadcrumb-fg-color});
--#{$prefix}bg-color: var(--#{$prefix}breadcrumb-bg-color, #{$breadcrumb-bg-color});
--#{$prefix}border-width: var(--#{$prefix}breadcrumb-border-width, #{$breadcrumb-border-width});
--#{$prefix}border-color: var(--#{$prefix}breadcrumb-border-color, #{$breadcrumb-border-color});
--#{$prefix}border-radius: var(--#{$prefix}breadcrumb-border-radius, #{$breadcrumb-border-radius});
--#{$prefix}item-padding-x: var(--#{$prefix}breadcrumb-item-padding-x, #{$breadcrumb-item-padding-x});
--#{$prefix}divider-color: var(--#{$prefix}breadcrumb-divider-color, #{$breadcrumb-divider-color});

Sass variables

These Sass variables are also exposed as CSS custom properties using the --cx- prefix. A Sass variable $variable-name becomes available as --cx-variable-name in CSS, allowing for styles to be modified dynamically on the page. See the context components page for more details.

scss/_variables.scss

$breadcrumb-font:               $cx-font-text-medium-normal;
$breadcrumb-padding-y:          0;
$breadcrumb-padding-x:          0;
$breadcrumb-item-padding-x:     .5rem;
$breadcrumb-margin-bottom:      1rem;
$breadcrumb-fg-color:           var(--#{$prefix}fg-subtle);
$breadcrumb-bg-color:           null;
$breadcrumb-divider-color:      var(--#{$prefix}fg-subtle);
$breadcrumb-divider:            quote("/");
$breadcrumb-divider-flipped:    $breadcrumb-divider;
$breadcrumb-border-width:       0;
$breadcrumb-border-color:       transparent;
$breadcrumb-border-radius:      null;