Breadcrumb - BEEQ Design System

A breadcrumb is a form of contextual navigation displaying a user’s position within a site hierarchy, enabling them to navigate back through the levels, while it should not be misleading as a primary navigation tool.

When to use

Use breadcrumbs when

Navigating large content hierarchies with more than two levels
Users need compact context for where they are in the navigation hierarchy
Users need to move back through parent levels from the current page

Do not use breadcrumbs when

They would substitute the primary navigation
The product has single-level navigation and breadcrumbs would add unnecessary clutter
The user is in a multistep process; use a progress indicator instead

Anatomy

Part	Element	Description
Icon	`bq-icon` or decorative icon	Optional visual cue before the first breadcrumb item
Divider	`separator` slot	The default slash separator or a custom separator element
Inactive breadcrumb	`bq-breadcrumb-item`	A parent navigation step rendered as a link or button
Current page	`bq-breadcrumb-item` with `aria-current="page"`	The last item indicating the user’s current location
Truncation	custom overflow or hidden items	Collapses long paths while preserving the first and last items
Dropdown	custom nested menu	Optional overflow menu for deep breadcrumb trails

Design guidelines

Placement

Breadcrumbs should appear near the top of the page, above the page title or directly below the page header.

Label and icon

States

All parent breadcrumb items share the same brand primary color. Each interactive state provides a distinct visual cue:

State	Visual treatment
Default	Brand primary color text, no decoration
Hover	Reduced opacity to signal interactivity
Focus	Visible focus ring around the item
Active	`:active` pressed appearance
Current page	Brand color text, non-interactive; `aria-current="page"` is set automatically

Sizing and spacing

Breadcrumb items use consistent internal padding and separator spacing controlled by CSS custom properties. You can adjust these tokens when integrating the breadcrumb into a custom page header:

--bq-breadcrumb-item--paddingY — vertical padding of each item
--bq-breadcrumb-item--padding-start / --bq-breadcrumb-item--padding-end — horizontal padding of each item
--bq-breadcrumb-item--padding-start-separator / --bq-breadcrumb-item--padding-end-separator — spacing around the separator

Truncation

Show a maximum of four items in the breadcrumb trail. When the path is deeper, keep the first (root) and last (current page) items visible and collapse the intermediate levels into a dropdown so users can still reach any level.

Usage

The examples below cover the most common ways to use breadcrumbs in BEEQ.

Default

Use a default breadcrumb to show the current page within a hierarchy. When href is not set, each breadcrumb item renders as a button.

Always place bq-breadcrumb-item elements directly inside bq-breadcrumb. Items rendered outside the component will not receive separator or aria-current handling.

Custom separator

Use the separator slot to replace the default / separator.

Use the same separator throughout a breadcrumb trail. Mixing separator styles in a single trail breaks visual consistency.

Options

The following example shows how to combine icons with breadcrumb items.

With icons

Icons next to labels help users recognize categories at a glance. Use size="16" icons and always pair them with a text label or aria-label for screen reader clarity.

Best practices

DoFor breadcrumbs on detail pages, include the page type (Create, Edit, View) followed by the item name.

Don’tAvoid indicating the item number or using dynamically generated names without context.

DoTruncate labels longer than 30 characters with an ellipsis and show the full text in a tooltip on hover.

Don’tDisplay overly long labels that wrap or truncate without a way to view the complete text.

DoShow a maximum of four items in the breadcrumb trail. For longer paths, truncate and show the first and last items.

Don’tDisplay more than four items in a single breadcrumb trail, as it overloads the visual and reduces usability.

DoMake all parent breadcrumb items clickable links, including the current page as the last non-interactive item.

Don’tDisplay the current page as a clickable link; it should be non-interactive text to reflect the user’s current location.

Accessibility

Navigation — navigate to each link in the breadcrumb using Tab and activate it with Enter.
Landmark label — use the label prop to set an aria-label on the <nav> landmark. The default value is Breadcrumbs; override it when multiple navigation regions exist on the same page.
Current page — the last breadcrumb item receives aria-current="page" automatically.
Icon-only items — when a breadcrumb item contains only an icon, set aria-label on the bq-breadcrumb-item to describe the destination (e.g. aria-label="Home page").
Decorative icons — when an icon appears alongside a visible text label, set aria-hidden="true" on the bq-icon so screen readers do not announce it twice.

API reference

Property	Attribute	Description	Type	Default
`label`	`label`	The `aria-label` attribute to describe the type of navigation	`string`	`'Breadcrumbs'`

Property	Attribute	Description	Type	Default
`href`	`href`	If set, the breadcrumb item will be rendered as an `<a>` with this `href`, otherwise, a `<button>` will be rendered	`string`	`undefined`
`rel`	`rel`	Where to display the link in the browser context. Relevant only if `href` is set	`string`	`'noreferrer noopener'`
`target`	`target`	Where to display the link in the browser context. Relevant only if `href` is set	`'_blank'` \| `'_parent'` \| `'_self'` \| `'_top'`	`undefined`

Events

Events are emitted by bq-breadcrumb-item.

Event	Description	Type
`bqBlur`	Handler to be called when item loses focus	`CustomEvent<HTMLBqBreadcrumbItemElement>`
`bqClick`	Handler to be called when item is clicked	`CustomEvent<HTMLBqBreadcrumbItemElement>`
`bqFocus`	Handler to be called when item is focused	`CustomEvent<HTMLBqBreadcrumbItemElement>`

Slots

Slot	Description
(default)	The default slot is used to add `bq-breadcrumb-item` items to the breadcrumb
`separator`	The slot to add a separator between breadcrumb items. Default separator is `/`

Slot	Description
(default)	The default slot is used to add content to the breadcrumb item

CSS parts

Part	Description
`navigation`	The `nav` tag that loads the breadcrumb items
`separator`	The container that wraps the separator element

Part	Description
`base`	The component wrapper container
`content`	The `span` tag that wraps the content item
`item`	The breadcrumb item wrapper (`button` or `a`)
`separator`	The `span` tag that wraps the separator element

CSS custom properties

Hide CSS variables

Variable	Description	Default
`--bq-breadcrumb-item--background`	Background color of the breadcrumb item	`transparent`
`--bq-breadcrumb-item--box-shadow`	Box shadow of the breadcrumb item	`none`
`--bq-breadcrumb-item--border-color`	Border color of the breadcrumb item	`transparent`
`--bq-breadcrumb-item--border-style`	Border style of the breadcrumb item	`none`
`--bq-breadcrumb-item--border-width`	Border width of the breadcrumb item	`var(--bq-stroke-s)`
`--bq-breadcrumb-item--border-radius`	Border radius of the breadcrumb item	`var(--bq-radius--s)`
`--bq-breadcrumb-item--line-height`	Line height of the breadcrumb item	`var(--bq-font-line-height--regular)`
`--bq-breadcrumb-item--text-color`	Text color of the breadcrumb item	`var(--bq-text--secondary)`
`--bq-breadcrumb-item--text-color-current`	Text color of the current breadcrumb item	`var(--bq-text--brand)`
`--bq-breadcrumb-item--text-size`	Text size of the breadcrumb item	`var(--bq-font-size--s)`
`--bq-breadcrumb-item--text-size-separator`	Text size of the breadcrumb item separator	`var(--bq-font-size--xs)`
`--bq-breadcrumb-item--padding-start`	Padding start of the breadcrumb item	`var(--bq-spacing-xs2)`
`--bq-breadcrumb-item--padding-end`	Padding end of the breadcrumb item	`var(--bq-spacing-xs2)`
`--bq-breadcrumb-item--paddingY`	Padding top and bottom of the breadcrumb item	`var(--bq-spacing-xs)`
`--bq-breadcrumb-item--padding-start-separator`	Padding start of the breadcrumb item separator	`var(--bq-spacing-xs2)`
`--bq-breadcrumb-item--padding-end-separator`	Padding end of the breadcrumb item separator	`var(--bq-spacing-xs2)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore all breadcrumb configurations in Storybook

Source code

View the breadcrumb implementation on GitHub

​When to use

​Anatomy

​Design guidelines

​Placement

​Label and icon

​States

​Sizing and spacing

​Truncation

​Usage

​Default

​Custom separator

​Options

​With icons

​Best practices

​Accessibility

​API reference

​bq-breadcrumb properties

​bq-breadcrumb-item properties

​Events

​Slots

​bq-breadcrumb

​bq-breadcrumb-item

​CSS parts

​bq-breadcrumb

​bq-breadcrumb-item

​CSS custom properties

​Resources

Interactive playground

Source code

When to use

Anatomy

Design guidelines

Placement

Label and icon

States

Sizing and spacing

Truncation

Usage

Default

Custom separator

Options

With icons

Best practices

Accessibility

API reference

`bq-breadcrumb` properties

`bq-breadcrumb-item` properties

Events

Slots

`bq-breadcrumb`

`bq-breadcrumb-item`

CSS parts

`bq-breadcrumb`

`bq-breadcrumb-item`

CSS custom properties

Resources