Breadcrumbs

Breadcrumbs

Breadcrumbs show the user’s location within a site hierarchy and provide quick navigation to parent pages. They help users understand where they are and navigate back through the site structure.

Installation

Copy the breadcrumb CSS from styles/docs.css or include the Standard stylesheet:

<link rel="stylesheet" href="standard.min.css">

Then use breadcrumb classes in your HTML:

<nav class="Breadcrumb" aria-label="Breadcrumb">
    <ol class="Breadcrumb-list">
        <li class="Breadcrumb-item"><a href="#">Home</a></li>
        <li class="Breadcrumb-item" aria-current="page">Current Page</li>
    </ol>
</nav>

Usage

The breadcrumb component uses semantic HTML with a <nav> landmark and an ordered list to convey hierarchy. The last item represents the current page and should not be a link.

Examples

Basic Breadcrumb

A simple trail of links separated by slashes.

With Home Icon

Add a home icon to the first item for visual clarity. Use aria-label when replacing text with an icon.

Separator Styles

Use modifier classes to change the separator character.

Truncated Breadcrumb

For deep hierarchies, collapse middle items with an ellipsis button that can reveal hidden levels.

Sizes

Breadcrumbs come in three sizes: small, medium (default), and large.

Small
Default
Large

Common Patterns

Page Header

Breadcrumbs typically appear above the page title.

Standard Design System

E-commerce Category

Show the product category hierarchy for shopping sites.

Documentation Site

Breadcrumbs in documentation help users navigate sections.

Customization

Override breadcrumb styles using CSS custom properties:

/* Custom separator */
.Breadcrumb--custom .Breadcrumb-item + .Breadcrumb-item::before {
    content: "→";
    color: var(--accent);
}

/* Custom link colors */
.Breadcrumb--brand .Breadcrumb-item a {
    color: var(--accent);
}

.Breadcrumb--brand .Breadcrumb-item a:hover {
    color: var(--accent-secondary);
    text-decoration: underline;
}

/* Pill-style breadcrumb */
.Breadcrumb--pills .Breadcrumb-item a {
    background: var(--bg-s);
    padding: var(--space-1) var(--space-2);
    border-radius: var(--space-4);
}

.Breadcrumb--pills .Breadcrumb-item a:hover {
    background: var(--bg-tertiary);
}

/* Custom separator icon */
.Breadcrumb--chevron .Breadcrumb-item + .Breadcrumb-item::before {
    content: "";
    width: 16px;
    height: 16px;
    background-image: url("data:image/svg+xml,...");
    background-size: contain;
}

API Reference

Base Classes

Class Description
.Breadcrumb Container element (use on <nav>)
.Breadcrumb-list Ordered list wrapper (use on <ol>)
.Breadcrumb-item Individual breadcrumb item (use on <li>)

Separator Variants

Class Description
.Breadcrumb--arrows Uses › as separator
.Breadcrumb--dots Uses • as separator

Size Classes

Class Description
.Breadcrumb--small Small text size (0.75rem)
.Breadcrumb--large Large text size (1rem)

Utility Classes

Class Description
.Breadcrumb-ellipsis Ellipsis button for truncated breadcrumbs

ARIA Attributes

Attribute Element Description
aria-label="Breadcrumb" <nav> Identifies the navigation landmark
aria-current="page" <li> Marks the current page item

CSS Reference

/* Base Breadcrumb */
.Breadcrumb {
  font-size: 0.875rem;
  color: var(--fg-3);
}

.Breadcrumb-list {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  list-style: none;
  margin: 0;
  padding: 0;
  gap: var(--space-1);
}

.Breadcrumb-item {
  display: inline-flex;
  align-items: center;
}

.Breadcrumb-item + .Breadcrumb-item::before {
  content: "/";
  margin-right: var(--space-1);
  color: var(--fg-3);
  opacity: 0.5;
}

.Breadcrumb-item a {
  color: var(--fg-3);
  text-decoration: none;
  transition: color 0.15s;
}

.Breadcrumb-item a:hover {
  color: var(--fg);
  text-decoration: underline;
}

.Breadcrumb-item a:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 2px;
  border-radius: var(--r-s);
}

.Breadcrumb-item[aria-current="page"] {
  color: var(--fg);
  font-weight: 500;
}

/* Separator Variants */
.Breadcrumb--arrows .Breadcrumb-item + .Breadcrumb-item::before {
  content: "›";
}

.Breadcrumb--dots .Breadcrumb-item + .Breadcrumb-item::before {
  content: "•";
}

/* Sizes */
.Breadcrumb--small {
  font-size: 0.75rem;
}

.Breadcrumb--large {
  font-size: 1rem;
}

/* Ellipsis */
.Breadcrumb-ellipsis {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: var(--space-1);
  background: none;
  border: none;
  color: var(--fg-3);
  cursor: pointer;
  border-radius: var(--r-s);
  transition: background-color 0.15s, color 0.15s;
}

.Breadcrumb-ellipsis:hover {
  background-color: var(--bg-s);
  color: var(--fg);
}

.Breadcrumb-ellipsis:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 2px;
}

Accessibility

Keyboard Support

Key Action
Tab Moves focus through breadcrumb links
Enter Activates the focused link
Space Activates the focused link or ellipsis button

Screen Readers

<!-- ✓ Proper landmark and labeling -->
<nav class="Breadcrumb" aria-label="Breadcrumb">
    <ol class="Breadcrumb-list">
        <li class="Breadcrumb-item"><a href="/">Home</a></li>
        <li class="Breadcrumb-item"><a href="/products">Products</a></li>
        <li class="Breadcrumb-item" aria-current="page">Widget</li>
    </ol>
</nav>

<!-- ✓ Icon-only home link with aria-label -->
<li class="Breadcrumb-item">
    <a href="/" aria-label="Home">
        <i class="ph ph-house"></i>
    </a>
</li>

<!-- ✓ Ellipsis button with descriptive label -->
<button class="Breadcrumb-ellipsis" aria-label="Show 3 more navigation levels">
    <i class="ph ph-dots-three"></i>
</button>

Important Guidelines

  1. Use <nav> with aria-label — Creates a navigation landmark for screen readers
  2. Use <ol> for the list — Conveys the ordered hierarchical structure
  3. Mark the current page — Use aria-current="page" on the last item
  4. Don’t link the current page — It’s redundant and confusing
  5. Label icon-only items — Use aria-label when text is replaced by icons

Best Practices

Do

  • ✓ Start with Home or root — Provide full navigational context
  • ✓ Keep labels short — Use concise, recognizable page names
  • ✓ Show hierarchy, not history — Breadcrumbs reflect site structure, not browsing path
  • ✓ Place consistently — Usually below the header, above the page title
  • ✓ Truncate deep hierarchies — Use ellipsis for paths deeper than 4-5 levels

Don’t

  • ✗ Link to the current page — It’s redundant and potentially confusing
  • ✗ Use on single-level sites — Breadcrumbs only make sense for hierarchies
  • ✗ Replace primary navigation — Breadcrumbs supplement, not replace, main nav
  • ✗ Use as browser history — Breadcrumbs are structural, not temporal
  • ✗ Skip accessibility attributes — Always include aria-label and aria-current