;
};
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.
Place breadcrumbs directly above the page title when the header contains navigation or actions.
Place breadcrumbs below the page header when an additional top bar or contextual toolbar is present.
### Label and icon
Use small icons (`size="16"`) paired with a text label to aid recognition. Never use an icon alone without a text label or an icon `label`.
Text-only labels work well in compact spaces or minimal interfaces. Keep labels short and match the destination page title exactly.
### 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** | Text color changes to the brand hover color to signal interactivity |
| **Focus** | Visible focus ring around the item |
| **Active** | `:active` pressed appearance |
| **Current page** | Secondary text color (`--bq-breadcrumb-item--text-color-current`); `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.
HomeMen's clothingShirtCasual shirts
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
HomeMen's clothingShirtCasual shirts
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBreadcrumb, BqBreadcrumbItem } from "@beeq/react";
HomeMen's clothingShirtCasual shirts
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBreadcrumb, BqBreadcrumbItem } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBreadcrumb, BqBreadcrumbItem],
template: `
HomeMen's clothingShirtCasual shirts
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
HomeMen's clothingShirtCasual shirts
```
### Custom separator
Use the `separator` slot to replace the default `/` separator.
HomeCatalogCasual shirts
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
HomeCatalogCasual shirts
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/react";
HomeCatalogCasual shirts
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBreadcrumb, BqIcon, BqBreadcrumbItem } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBreadcrumb, BqIcon, BqBreadcrumbItem],
template: `
HomeCatalogCasual shirts
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
HomeCatalogCasual shirts
```
Use the same separator throughout a breadcrumb trail. Mixing separator styles in a single trail breaks visual consistency.
### Intercepting navigation
When a `bq-breadcrumb-item` has an `href`, activating it navigates to that URL. The `bqClick` event is cancelable: call `event.preventDefault()` on the event to stop the browser from following the link. Use this to route through a client-side router, prompt the user before leaving an unsaved form, or run analytics before navigating.
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
HomeCatalogCasual shirts
```
## 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 set `label` on the icon for screen reader clarity.
Men's Clothing
Casual shirts
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Men's Clothing
Casual shirts
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/react";
Men's Clothing
Casual shirts
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqBreadcrumb, BqBreadcrumbItem, BqIcon } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqBreadcrumb, BqBreadcrumbItem, BqIcon],
template: `
Men's Clothing
Casual shirts
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Men's Clothing
Casual shirts
```
## Best practices
Do
For breadcrumbs on detail pages, include the page type (Create, Edit, View) followed by the item name.
Don't
Avoid indicating the item number or using dynamically generated names without context.
Do
Truncate labels longer than 30 characters with an ellipsis and show the full text in a tooltip on hover.
Don't
Display overly long labels that wrap or truncate without a way to view the complete text.
Do
Show a maximum of four items in the breadcrumb trail. For longer paths, truncate and show the first and last items.
Don't
Display more than four items in a single breadcrumb trail, as it overloads the visual and reduces usability.
Do
Make all parent breadcrumb items clickable links, including the current page as the last non-interactive item.
Don't
Display 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 `
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
| 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.