Breadcrumbs - Elements

Breadcrumbs show users their current location relative to the information architecture and enable them to quickly move up to a parent level or previous step.

ElementsreleasedReactreleasedVuereleased

ElementsReactVue

Example theme:

DBA lightFinn lightTori lightBlocket lightNeutral lightVend lightDBA darkFinn darkTori darkBlocket darkNeutral darkVend dark

Accessibility

Breadcrumbs are exposed as navigation so assistive technology users can identify the path to the current page.

Label The Navigation

The component has a localized default accessible label. Use aria-label when the default label is not specific enough, especially if the page has more than one breadcrumb trail or other navigation landmarks nearby.

<w-breadcrumbs aria-label="Product category path">
  <w-breadcrumb-item href="/marketplace">Marketplace</w-breadcrumb-item>
  <w-breadcrumb-item href="/marketplace/furniture">Furniture</w-breadcrumb-item>
  <w-breadcrumb-item href="/marketplace/furniture/1234566" current-page>Sofas</w-breadcrumb-item>
</w-breadcrumbs>

Mark The Current Page

The last breadcrumb item should represent the current page and include the current-page attribute which in turn ensures correct accessibility semantics are used.

Omit an href attribute for the current page when it should not be clickable:

<w-breadcrumbs aria-label="You are here">
  <w-breadcrumb-item href="/real-estate">Real estate</w-breadcrumb-item>
  <w-breadcrumb-item href="/real-estate/homes">Homes for sale</w-breadcrumb-item>
  <w-breadcrumb-item current-page>Oslo</w-breadcrumb-item>
</w-breadcrumbs>

Keep The Trail Predictable

Order breadcrumb items from the broadest parent to the current page. Use concise link text that names the destination.

Do not include separator characters in the markup. The component adds visual separators between items.

Breadcrumbs should support orientation within the site hierarchy. They should not be used as the only way to navigate the site or as a replacement for a page heading.

Usage

Breadcrumbs show where the current page sits in a site hierarchy and let users move back to parent pages.

Use w-breadcrumbs near the top of a page or section, before the main page heading or primary content. Add each breadcrumb item as a direct child. The component adds separators automatically.

Basic Breadcrumbs

Use w-breadcrumb-item components with an href for parent pages and mark the current page with the current-page attribute.

<w-breadcrumbs aria-label="You are here">
  <w-breadcrumb-item href="/real-estate">Real estate</w-breadcrumb-item>
  <w-breadcrumb-item href="/real-estate/homes">Homes for sale</w-breadcrumb-item>
  <w-breadcrumb-item current-page>Oslo</w-breadcrumb-item>
</w-breadcrumbs>

Current Page

The current page should be the last breadcrumb item.

By default the current-page will not be presented as a link, setting href will change it to a link.

<w-breadcrumbs aria-label="You are here">
  <w-breadcrumb-item href="/real-estate">Real estate</w-breadcrumb-item>
  <w-breadcrumb-item href="/real-estate/homes">Homes for sale</w-breadcrumb-item>
  <w-breadcrumb-item href="/real-estate/homes/12345612" current-page>Oslo</w-breadcrumb-item>
</w-breadcrumbs>

Content Guidelines

Keep breadcrumb labels short and ordered from broadest section to most specific page. Do not add slash separators yourself; the component inserts them between items.

Breadcrumbs should not replace the page heading, primary navigation, or step navigation in a process.

Examples

Basic

  <w-breadcrumbs>
    <w-breadcrumb-item href="/real-estate">Real estate</w-breadcrumb-item>
    <w-breadcrumb-item href="/real-estate/homes">Homes for sale</w-breadcrumb-item>
    <w-breadcrumb-item current-page>Oslo</w-breadcrumb-item>
  </w-breadcrumbs>

Custom Accessible Label

  <w-breadcrumbs aria-label="Product category path">
    <w-breadcrumb-item href="#/marketplace">Marketplace</w-breadcrumb-item>
    <w-breadcrumb-item href="#/marketplace/furniture">Furniture</w-breadcrumb-item>
    <w-breadcrumb-item current-page>Sofas</w-breadcrumb-item>
  </w-breadcrumbs>

Short Path

  <w-breadcrumbs>
    <w-breadcrumb-item href="#/help">Help</w-breadcrumb-item>
    <w-breadcrumb-item current-page>Contact us</w-breadcrumb-item>
  </w-breadcrumbs>

Styling API

Breadcrumbs

The breadcrumbs components support styling through component tokens (CSS custom properties with a --w-c- prefix) and parts.

w-breadcrumbs does not expose component-specific tokens. Set w-breadcrumb-item tokens on w-breadcrumbs or another ancestor to style all items in a breadcrumb trail.

w-breadcrumbs {
	--w-c-breadcrumb-item-link-color: var(--w-s-color-text-link);
	--w-c-breadcrumb-item-separator-spacing: 1.2rem;
}

Breadcrumb Item

The w-breadcrumb-item component supports styling through component tokens and parts.

Component tokens

Set these on w-breadcrumb-item to override one item, or on w-breadcrumbs to let the values inherit into all item children.

w-breadcrumb-item {
	--w-c-breadcrumb-item-link-color-hover: var(--w-s-color-text-link-hover);
	--w-c-breadcrumb-item-font-weight: 700;
}

Layout and typography

Token	Purpose	Default
--w-c-breadcrumb-item-font-size	Font size for the label and separator	inherited font size
--w-c-breadcrumb-item-line-height	Line height for the label and separator	1.5
--w-c-breadcrumb-item-font-weight	Font weight for the label and separator	400
--w-c-breadcrumb-item-padding-x	Inline padding for linked items	0
--w-c-breadcrumb-item-padding-y	Block padding for linked items	0

Link color

Token	Purpose	Default
--w-c-breadcrumb-item-link-color	Color for linked items	var(--w-s-color-text-link)
--w-c-breadcrumb-item-link-color-hover	Color for linked items on hover	link color
--w-c-breadcrumb-item-link-color-active	Color for linked items in the active state	link color

Text color

Token	Purpose	Default
--w-c-breadcrumb-item-text-color	Color for non-linked items	var(--w-s-color-text)

Separator

Token	Purpose	Default
--w-c-breadcrumb-item-separator-color	Color for the separator	var(--w-s-color-icon)
--w-c-breadcrumb-item-separator-spacing	Inline margin on each side of the separator	0.8rem

The separator uses --w-c-breadcrumb-item-font-size, --w-c-breadcrumb-item-line-height, and --w-c-breadcrumb-item-font-weight.

Focus

Token	Purpose	Default
--w-c-breadcrumb-item-outline-width	Focus outline width for linked items	native focus outline
--w-c-breadcrumb-item-outline-color	Focus outline color for linked items	native focus outline
--w-c-breadcrumb-item-outline-offset	Focus outline offset for linked items	native focus outline

Parts

Use ::part(...) from outside the component.

• link - the link element rendered when href is set.
• text - the text element rendered when href is omitted.
• separator - the separator rendered after non-current items.

Example:

w-breadcrumb-item::part(link) {
	text-decoration-thickness: 2px;
}

w-breadcrumb-item::part(separator) {
	margin-inline: 1.2rem;
}

Notes

• separator is not rendered when current-page is set.
• Use link for linked breadcrumb items and text for non-linked breadcrumb items.
• Link color, padding, and focus tokens apply only when href is set.
• Focus tokens do not make non-linked breadcrumb items keyboard-focusable.

<w-breadcrumbs> API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties

Name	Type	Default	Summary
ariaLabel (JS only)	string | null	-	Accessible label for the breadcrumb navigation.

Property Details

ariaLabel (JS only)

Accessible label for the breadcrumb navigation. Defaults to the localized "You are here" label. Set aria-label when the default label is not specific enough for the page.

• Type: string | null
• Default: -

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system