# Breadcrumb
> Breadcrumb shows where the user is in the hierarchy and lets them move back up it.

## Import

```js
import { Breadcrumb } from '@volue/wave-react';
```

Breadcrumb is a compound component. Each part owns exactly one element, so you
can style the list and the individual crumbs directly.

- `Breadcrumb.Root`: the `<nav>` landmark. Requires a `label`.
- `Breadcrumb.List`: the ordered list holding the crumbs.
- `Breadcrumb.Item`: a single crumb: a link, or the current page.

## When to use

Use Breadcrumb when content is nested several levels deep and users need a way
back up.

If you’re using other navigational elements, such as
[Sidebar Navigation](https://wave.volue.com/components/sidebar-navigation.md) or
[Nav Bar](https://wave.volue.com/components/nav-bar.md), consider whether your users need the additional
support of breadcrumbs.

## Examples

### Basic

Mark the crumb representing the current page with `isCurrent`. It renders as
non-interactive text with `aria-current="page"`; every other crumb is a link.

> **Tip**
>
> Avoid more than 5 levels. Long trails wrap onto a second line and are hard to
> scan.

```jsx resizable=true
<Breadcrumb.Root label="Breadcrumb">
  <Breadcrumb.List>
    <Breadcrumb.Item href="#">{'Production planning'}</Breadcrumb.Item>
    <Breadcrumb.Item href="#">{'Hydro portfolio'}</Breadcrumb.Item>
    <Breadcrumb.Item href="#">{'Northern region'}</Breadcrumb.Item>
    <Breadcrumb.Item href="#">{'Turbine 4'}</Breadcrumb.Item>
    <Breadcrumb.Item isCurrent>{'Maintenance'}</Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>
```

### Sizes

`Breadcrumb` comes in two sizes: `medium` and `small`. By default, it uses
`medium` size. The separator scales with the label automatically.

```jsx
<Flex flow="column" gap="spacingL">
  <Breadcrumb.Root label="Medium breadcrumb" size="medium">
    <Breadcrumb.List>
      <Breadcrumb.Item href="#">{'Item 1'}</Breadcrumb.Item>
      <Breadcrumb.Item href="#">{'Item 2'}</Breadcrumb.Item>
      <Breadcrumb.Item isCurrent>{'Item 3'}</Breadcrumb.Item>
    </Breadcrumb.List>
  </Breadcrumb.Root>
  <Breadcrumb.Root label="Small breadcrumb" size="small">
    <Breadcrumb.List>
      <Breadcrumb.Item href="#">{'Item 1'}</Breadcrumb.Item>
      <Breadcrumb.Item href="#">{'Item 2'}</Breadcrumb.Item>
      <Breadcrumb.Item isCurrent>{'Item 3'}</Breadcrumb.Item>
    </Breadcrumb.List>
  </Breadcrumb.Root>
</Flex>
```

### Truncation

Anything longer than roughly twenty characters will be clipped with an ellipsis.
The full label is available when hovering.

```jsx
<Breadcrumb.Root label="Breadcrumb">
  <Breadcrumb.List>
    <Breadcrumb.Item href="#">{'Production planning'}</Breadcrumb.Item>
    <Breadcrumb.Item href="#">
      {'Northern region hydro portfolio 2026'}
    </Breadcrumb.Item>
    <Breadcrumb.Item isCurrent>
      {'Turbine 4 maintenance window'}
    </Breadcrumb.Item>
  </Breadcrumb.List>
</Breadcrumb.Root>
```

### With routing

If you need to use the `Link` component provided by your routing package (e.g.
[React Router](https://reactrouter.com/en/main) or
[Next.js](https://nextjs.org/docs/api-reference/next/link)), it's recommended to
compose it with `Breadcrumb.Item`. Any props you add go to that component, so
`to`, `href` and click handlers all work as usual.

```jsx
import { Link } from 'react-router';
import { Breadcrumb } from '@volue/wave-react';

function App() {
  return (
    <Breadcrumb.Root label="Breadcrumb">
      <Breadcrumb.List>
        <Breadcrumb.Item as={Link} to="/">
          {'Home'}
        </Breadcrumb.Item>
        <Breadcrumb.Item as={Link} to="/products">
          {'Products'}
        </Breadcrumb.Item>
        <Breadcrumb.Item isCurrent>{'Turbine 4'}</Breadcrumb.Item>
      </Breadcrumb.List>
    </Breadcrumb.Root>
  );
}
```

<Card
  href="https://next--63ac6ba300bd3c91074bc891.chromatic.com/?path=/story/components-breadcrumb--with-router"
  title="See complete example in Storybook"
  actionIcon="externalLink"
/>

## Accessibility

- `Breadcrumb.Root` renders a `<nav>` landmark and requires a `label`, which
  becomes its `aria-label`.
- Two breadcrumbs on one page need **distinct** `label`s; duplicate landmark
  names are an accessibility violation.
- The crumbs are an ordered list, so assistive technology announces position and
  total.
- By default the crumb marked `isCurrent` carries `aria-current="page"` and is
  not focusable. It is plain text rather than a disabled link, so it is skipped
  in the tab order.
- Truncation is visual only. The full label stays in the DOM, so it remains the
  crumb's accessible name and can still be selected and copied.

## API reference

### Breadcrumb.Root

| Name    | Type                  | Default  | Description                                                                                                                                                                                                                                   | Required |
| ------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`   | `StitchesCss`         |          | Apply styles directly to a component in a similar way how you would define inline styles. Wave uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `label` | `string`              |          | The `aria-label` of the navigation landmark to use for screen readers.                                                                                                                                                                        | Yes      |
| `size`  | `'small' \| 'medium'` | `medium` | The size of the Breadcrumb. `Breadcrumb.List` and `Breadcrumb.Item` inherit it.                                                                                                                                                               |          |

### Breadcrumb.List

| Name  | Type          | Default | Description                                                                                                                                                                                                                                   | Required |
| ----- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Wave uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |

### Breadcrumb.Item

| Name        | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                                                                     | Required |
| ----------- | --------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`        | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `a`     | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   Do not pass an interactive component alongside `isCurrent` — the crumb would be focusable and clickable while still styled as plain text. |          |
| `css`       | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Wave uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                                                                   |          |
| `children`  | `string`                                                  |         | The crumb label. Crumbs take plain text only, so that truncation and the tooltip have a single label to work with.                                                                                                                                                                                                                              | Yes      |
| `isCurrent` | `boolean`                                                 | `false` | Marks this crumb as the page the user is on. It renders as non-interactive text with `aria-current="page"` instead of a link.                                                                                                                                                                                                                   |          |