# Breadcrumb

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/breadcrumb
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=346-2

```tsx
import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';
import { GBFlag } from '@commenda/pathfinder/flags/GBFlag';

export const BreadcrumbDefault = () => (
  <Breadcrumb
    label="Entity breadcrumb"
    ancestors={[
      { id: 'entities', label: 'Entities', linkConfig: { href: '#entities' } },
      {
        id: 'acme',
        label: 'Acme UK Ltd',
        leadingIcon: <GBFlag size={16} />,
        linkConfig: { href: '#acme' },
      },
    ]}
    current={{ label: 'Annual report 2027' }}
  />
);
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from `@commenda/pathfinder/breadcrumb`. Interactive callbacks belong in a client component in Next.js App Router.

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `ancestors` | `readonly BreadcrumbAncestor[]` | required | Required; each has id, label, linkConfig, optional leadingIcon |
| `current` | `BreadcrumbCurrent` | required | Required; never a link |
| `label` | `string` | optional | Breadcrumb; names the navigation landmark |
| `pageActionsConfig` | `{ menu: DropdownMenu; label?: string; }` | optional | Optional; trigger defaults to Page actions |
| `overflowLabel` | `string` | optional | Show parent pages |
| `className` | `string` | optional | Additional classes for the component root. |
| `id` | `string` | optional | Stable HTML identifier for the component. |

### current fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `leadingIcon` | `ReactElement<any, string \| React.JSXElementConstructor<any>>` | No |  |

### pageActionsConfig fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `menu` | `DropdownMenu` | Yes |  |
| `label` | `string` | No |  |

### pageActionsConfig.menu fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groups` | `DropdownGroup[]` | Yes |  |

Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Item IDs/values must be unique and stable.

## Usage rules [#usage-rules]

`linkConfig` requires `href`, with optional `target`, `rel`, and `render(anchorProps)` for Next Link or another anchor-compatible component. Forward all supplied props and the ref. Collapsed items remain real links inside the menu, preserving browser navigation and modified clicks.

Beyond four levels, the component keeps the root, immediate parent, and current page. It derives hidden ancestors; do not maintain a second collapsed list. Labels truncate at 240 and reveal full text on hover/focus when truncated. The current page is not a link. Tabs never add breadcrumb levels. Show entity flags with the existing flag components.

Page actions render only when supplied with a nonempty menu. In a page header, avoid a second visible copy of the current title; the enclosing page still owns a semantic heading.

## Examples [#examples]

### Collapsed [#collapsed]


```tsx
import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';

export const BreadcrumbCollapsed = () => (
  <Breadcrumb
    label="Filing breadcrumb"
    ancestors={['Entities', 'Acme UK Ltd', 'Filings', 'Annual reports'].map(
      (label) => ({
        id: label,
        label,
        linkConfig: { href: `#${encodeURIComponent(label)}` },
      })
    )}
    current={{ label: 'Delaware annual report 2027' }}
  />
);
```


### Actions [#actions]


```tsx
import { useState } from 'react';

import { Breadcrumb } from '@commenda/pathfinder/breadcrumb';

export const BreadcrumbActions = () => {
  const [message, setMessage] = useState('');

  return (
    <div>
      <Breadcrumb
        label="Entity page breadcrumb"
        ancestors={[]}
        current={{ label: 'Annual report 2027' }}
        pageActionsConfig={{
          menu: {
            groups: [
              {
                id: 'page',
                items: [
                  {
                    id: 'duplicate',
                    label: 'Duplicate',
                    type: 'action',
                    onClick: () => {
                      setMessage('Report duplicated');
                    },
                  },
                ],
              },
            ],
          },
        }}
      />
      <output>{message}</output>
    </div>
  );
};
```


## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Breadcrumb [#breadcrumb]

Source: [346:10629](https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=346-10629), crumb 346:56, docs 348:309.

- `BREADCRUMB-01` — Source: final crumb is current, not a link. Past four levels retain root and last two. Crumbs are 28 high, side padding 6, radius 6, Label/13 Strong; chevron 12, gap 2. Truncate labels at 240 and expose full names on hover/focus.
- `BREADCRUMB-02` — Source: real names; entities lead with flags. Tabs never add levels. Do not add a redundant Back button or repeat the visible page title below the breadcrumb. The enclosing page supplies its semantic heading.
- `BREADCRUMB-03` — Pathfinder: ancestors require stable IDs and native linkConfig; current is a separate non-link object. Page actions render only for a supplied nonempty menu, with a localized accessible label. Hidden ancestors retain native anchor behavior through recursive Dropdown link items.