# dds-breadcrumb



<!-- Auto Generated Below -->


## Overview

One step in a breadcrumb trail: a link to a page above the current one, or the current page itself as plain text. Place it directly inside a `dds-breadcrumb-group`, which names the trail and marks the last item as current.

## Usage

### Breadcrumb

#### Placing a breadcrumb in a trail

A `dds-breadcrumb` is one step in a trail. Place each one as a direct child of a `dds-breadcrumb-group`, in order from the top of the site down to the current page. The separator after each step is hidden on whichever step is the last child of its parent, so a wrapper element around the steps, or an unrelated element placed after the last one, changes which step loses its separator.

```html
<dds-breadcrumb-group aria-label="Breadcrumb">
  <dds-breadcrumb href="/">Home</dds-breadcrumb>
  <dds-breadcrumb href="/products">Products</dds-breadcrumb>
  <dds-breadcrumb aria-current="page">Running shoes</dds-breadcrumb>
</dds-breadcrumb-group>
```

#### The current page

A step that carries `aria-current` renders as plain text instead of a link, even when it also has an `href`, because a link to the page you are already on is noise. It is also removed from the tab order. Mark the step for the page the user is on with `aria-current="page"`.

The current step is announced through `aria-current` on a text node, and some screen readers do not announce that as clearly as they announce a link. The surrounding `nav` landmark and the position of the step as the last item in the list carry the rest of the meaning, so keep the trail inside its group.

A step does not have to be the last one to be current. Setting `aria-current` on an earlier step keeps its separator, because the separator depends only on position.

```html
<dds-breadcrumb-group aria-label="Breadcrumb">
  <dds-breadcrumb href="/">Home</dds-breadcrumb>
  <dds-breadcrumb aria-current="page">Products</dds-breadcrumb>
  <dds-breadcrumb href="/products/shoes">Shoes</dds-breadcrumb>
</dds-breadcrumb-group>
```

#### Links that leave the site

Set `external` on a step whose `href` goes to another site. It opens in a new tab and shows an external link icon after the label.

```html
<dds-breadcrumb href="https://dentsu.com" external>dentsu.com</dds-breadcrumb>
```

#### Disabling a step

`disabled` makes a step inert: it keeps its place in the trail but is not focusable and does not navigate. A disabled step is skipped by keyboard users, so reserve it for a step the user cannot reach rather than one that is merely uninteresting.

```html
<dds-breadcrumb href="/archive" disabled>Archive</dds-breadcrumb>
```

#### Listening for focus

A focusable step emits `ddsFocus` and `ddsBlur`. React 19 passes a custom element's handler name through to `addEventListener` with only `on` removed, so write `onddsFocus` and `onddsBlur`, not `onDdsFocus`. Clicks reach the host as native `click` events and need no `dds` event.

```jsx
<dds-breadcrumb
  href="/products"
  onddsFocus={() => console.log("focused")}
  onddsBlur={() => console.log("blurred")}
>
  Products
</dds-breadcrumb>
```

#### Long trails

A trail wraps onto further lines when it does not fit. It does not collapse into an overflow indicator: collapsing would need a label for the indicator, and a component supplies no text of its own. When a trail is too long for your layout, shorten it where the content is authored.



## Properties

| Property   | Attribute  | Description                                                                           | Type                  | Default     |
| ---------- | ---------- | ------------------------------------------------------------------------------------- | --------------------- | ----------- |
| `disabled` | `disabled` | Renders the item inert: it is not focusable and does not navigate.                    | `boolean`             | `false`     |
| `external` | `external` | Opens the link in a new tab and appends an external link icon.                        | `boolean`             | `false`     |
| `href`     | `href`     | The URL to link to. Ignored while `disabled`, and while the item is the current page. | `string \| undefined` | `undefined` |


## Events

| Event      | Description                        | Type                |
| ---------- | ---------------------------------- | ------------------- |
| `ddsBlur`  | Emitted when the link loses focus. | `CustomEvent<void>` |
| `ddsFocus` | Emitted when the link gains focus. | `CustomEvent<void>` |


## Slots

| Slot        | Description                    |
| ----------- | ------------------------------ |
|             | The default slot               |
| `"default"` | Slot for the breadcrumb label. |


## Shadow Parts

| Part          | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| `"root"`      | The inner `<a>`, or the `<span>` while the item is the current page. |
| `"separator"` | The glyph drawn after the item. Hidden on the last item.             |


## Dependencies

### Depends on

- [dds-icon](../icon)

### Graph
```mermaid
graph TD;
  dds-breadcrumb --> dds-icon
  style dds-breadcrumb fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*