# Breadcrumbs (w-breadcrumbs)

## Description

Shows the navigation structure for the current page.

Renders direct child links and non-link elements as a breadcrumb trail, inserts separators between items, and exposes the trail as navigation.

[Warp component reference](https://warp-ds.github.io/docs/components/breadcrumbs/frameworks/elements)

## 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.

```html
<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.

```html
<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.

## 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.

```html
<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:

```html
<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.

## Examples

### Basic

<elements-example>

```html
  <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>
```

</elements-example>

### Custom Accessible Label

<elements-example>

```html
  <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>
```

</elements-example>

### Short Path

<elements-example>

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

</elements-example>

## 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.

```css
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.

```css
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:

```css
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: `-`