> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# Breadcrumbs

The location trail for a page that sits deep in a hierarchy — each ancestor links up, and the last item is the page you are on. Skip it in a flat app of one or two levels, and never use it to move between peers at the same level: that is `Tabs`. It shows vertical hierarchy only, and complements the sidebar rather than replacing it.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/Breadcrumbs) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/navigation-breadcrumbs--overview)

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { Home } from '@wallarm-org/design-system/icons';

export const Basic = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs data-testid='breadcrumbs'>
        <BreadcrumbsItem href='#home'>Home</BreadcrumbsItem>
        <BreadcrumbsItem href='#products'>Products</BreadcrumbsItem>
        <BreadcrumbsItem href='#current'>Current Page</BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

## Usage

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { Home } from '@wallarm-org/design-system/icons';
```

## Examples

### Single item

One item is the current page and nothing more — which is the case where a breadcrumb has stopped earning its space.

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';

export const SingleItem = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#current'>Current Page</BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

### With icons

An icon inside an item, for a level whose type is worth showing as well as naming.

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { CircleDashed, Home } from '@wallarm-org/design-system/icons';

export const WithIcons = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#home'>
          <Home size='md' />
          Home
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#category'>
          <CircleDashed size='md' />
          Category
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#subcategory'>
          Subcategory
          <CircleDashed size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem onClick={onCurrentPageClick}>
          <CircleDashed size='md' />
          Current Page
          <CircleDashed size='md' />
        </BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

### With interactive items

Items that call a handler instead of following an `href`, for a trail wired to a router rather than to URLs.

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { ChevronDown, CircleDashed, Home } from '@wallarm-org/design-system/icons';

export const WithInteractiveItems = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#home'>Home</BreadcrumbsItem>
        <BreadcrumbsItem onClick={onCategoryClick}>
          <CircleDashed size='md' />
          Category
          <ChevronDown size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#current'>Current Page</BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

### Icons only

Icons with no text. Each item needs its own `aria-label`, since the icon is then the only thing naming the level.

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { CircleDashed, Home } from '@wallarm-org/design-system/icons';

export const IconsOnly = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#home' aria-label='Home'>
          <Home size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#dashboard' aria-label='Dashboard'>
          <CircleDashed size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#projects' aria-label='Projects'>
          <CircleDashed size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#settings' aria-label='Settings'>
          <CircleDashed size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem href='#security' aria-label='Security'>
          <CircleDashed size='md' />
        </BreadcrumbsItem>
        <BreadcrumbsItem aria-label='Current page' onClick={onCurrentPageClick}>
          <CircleDashed size='md' />
        </BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

### With truncation

A long trail folded behind a `BreadcrumbsEllipsis`, which expands the middle on click. The first and current items always stay.

```tsx
import { useState } from 'react';
import { Breadcrumbs, BreadcrumbsEllipsis, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { Home } from '@wallarm-org/design-system/icons';
import { Tooltip, TooltipContent, TooltipTrigger } from '@wallarm-org/design-system/Tooltip';

export const WithTruncation = () => {
  const [showAll, setShowAll] = useState(false);

  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#home'>Home</BreadcrumbsItem>
        <BreadcrumbsItem href='#level1'>Level 1</BreadcrumbsItem>
        {!showAll ? (
          <Tooltip>
            <TooltipTrigger asChild>
              <BreadcrumbsEllipsis onClick={() => setShowAll(true)} />
            </TooltipTrigger>
            <TooltipContent>WIP</TooltipContent>
          </Tooltip>
        ) : (
          [
            <BreadcrumbsItem key='level2' href='#level2'>
              Level 2
            </BreadcrumbsItem>,
            <BreadcrumbsItem key='level3' href='#level3'>
              Level 3
            </BreadcrumbsItem>,
          ]
        )}
        <BreadcrumbsItem href='#penultimate'>Penultimate</BreadcrumbsItem>
        <BreadcrumbsItem href='#current'>Current Page</BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

### Long breadcrumbs

What a trail of long labels actually does today: it runs on. Per-item truncation is drawn in Figma but not shipped, so keep labels short.

```tsx
import { Breadcrumbs, BreadcrumbsItem } from '@wallarm-org/design-system/Breadcrumbs';
import { Home } from '@wallarm-org/design-system/icons';

export const LongBreadcrumbs = () => {
  return (
    <div className='flex items-center justify-center w-full p-8 min-h-[400px]'>
      <Breadcrumbs>
        <BreadcrumbsItem href='#home'>Home</BreadcrumbsItem>
        <BreadcrumbsItem href='#products'>Products & Services</BreadcrumbsItem>
        <BreadcrumbsItem href='#category'>Technology Category</BreadcrumbsItem>
        <BreadcrumbsItem href='#subcategory'>Software Development</BreadcrumbsItem>
        <BreadcrumbsItem href='#area'>Web Development Tools</BreadcrumbsItem>
        <BreadcrumbsItem onClick={onCurrentPageClick}>
          Frontend Frameworks and Libraries
        </BreadcrumbsItem>
      </Breadcrumbs>
    </div>
  );
};
```

## Props

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |
| data-testid    | `string \| undefined`                                |         |             |

### BreadcrumbsEllipsis

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| disabled       | `boolean \| undefined`                               |         |             |
| name           | `string \| undefined`                                |         |             |
| type           | `"button" \| "submit" \| "reset" \| undefined`       |         |             |
| value          | `string \| number \| readonly string[] \| undefined` |         |             |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

### BreadcrumbsItem

| Prop       | Type                                                                     | Default | Description                                                                       |
| ---------- | ------------------------------------------------------------------------ | ------- | --------------------------------------------------------------------------------- |
| href       | `string \| undefined`                                                    |         | If provided, renders as a link instead of button                                  |
| onClick    | `MouseEventHandler<HTMLButtonElement \| HTMLAnchorElement> \| undefined` |         | Click handler for buttons                                                         |
| aria-label | `string \| undefined`                                                    |         | ARIA label for accessibility                                                      |
| isCurrent  | `boolean \| undefined`                                                   | `false` | @internal - Whether this is the current/active page (set automatically by parent) |

### BreadcrumbsScopeSwitcher

| Prop        | Type                                | Default | Description                             |
| ----------- | ----------------------------------- | ------- | --------------------------------------- |
| value \*    | `string`                            |         |                                         |
| items \*    | `ScopeSwitcherItem[]`               |         |                                         |
| onSelect \* | `(item: ScopeSwitcherItem) => void` |         |                                         |
| isCurrent   | `boolean \| undefined`              | `false` | @internal - set automatically by parent |

### BreadcrumbsSeparator

| Prop           | Type                                                 | Default | Description |
| -------------- | ---------------------------------------------------- | ------- | ----------- |
| defaultChecked | `boolean \| undefined`                               |         |             |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |         |             |
| autoFocus      | `boolean \| undefined`                               |         |             |
| id             | `string \| undefined`                                |         |             |
| tabIndex       | `number \| undefined`                                |         |             |
| title          | `string \| undefined`                                |         |             |
| rel            | `string \| undefined`                                |         |             |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |         |             |

## Explorer