Skip to main content

Breadcrumb

Hierarchical navigation trail showing the current page's position in the site structure. Renders as a semantic <nav> with an ordered list and a customizable divider. On viewports narrower than --breakpoint-xs (480px) the list collapses to a single "← parent" link (the second-to-last item). links is an array of objects with text and optional url. Items without a url render as plain text. By default the last item is rendered as an anchor (with aria-current="page" on the <a>); set use_link_for_active: false to render it as plain text instead, in which case aria-current="page" moves to the <li>.

Usage​

When to use

  • On pages that sit inside a hierarchy more than one level deep
  • On interior content pages to give users context and a route back to the parent
  • Inside the hero on pages that use a hero component

When not to use

  • On homepages and top-level landing pages
  • On pages where the user arrives via a flat navigation pattern (e.g. single-page sites)
  • As a substitute for primary navigation

Do

  • Use <ol> because the order is meaningful
  • Mark the current page with aria-current="page"
  • Provide a mobile-compact variant that surfaces the parent link

Don't

  • Include the current page as a link unless the page actually navigates somewhere different
  • Expose the divider to assistive tech - it is a decorative CSS pseudo-element and must be hidden from the accessibility tree
  • Style the aria-label as a visible label - it is an accessibility hook only

API​

Props​

PropTypeDefaultDescription
linksarray-Array of {text, url} link objects. The last item is the current page.
labelstringBreadcrumbAccessible name for the navigation landmark.
use_link_for_activebooleantrueWhen true, the last item renders as an anchor with aria-current="page". When false, it renders as plain text.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.

Examples​

Custom divider​

Breadcrumb with an alternate divider character set via --breadcrumb-divider.

Mobile compact​

Mobile variant showing only the parent link (← Parent).

Active as text​

The current page renders as plain text rather than a link, while still carrying aria-current="page".

Accessibility​

  • WCAG 2.2 AA
  • Container is a <nav> with aria-label="Breadcrumb".
  • List is an <ol> because the order is meaningful.
  • Current page uses aria-current="page" on the last item.
  • Divider is decorative and must not be announced.
  • Class is a styling hook only; aria-label is the accessibility hook. Data attributes are reserved for JS behavior hooks.
  • hero - breadcrumb is rendered inside the hero on pages that use one
  • header - alternative top-of-page navigation element