# Breadcrumb

> Hierarchical navigation trail with custom separators and truncation.

- Available in: `@sisyphos-ui/react`, `@sisyphos-ui/vue`, `@sisyphos-ui/angular`
- Docs: https://www.sisyphosui.com/docs/components/breadcrumb
- WAI-ARIA pattern: [Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)

## Installation

Pick the framework binding that matches your stack:

```bash
pnpm add @sisyphos-ui/react   # React 18+
pnpm add @sisyphos-ui/vue     # Vue 3+
pnpm add @sisyphos-ui/angular # Angular 17+
```

## Import

```tsx
import "@sisyphos-ui/react/styles.css";
import { Breadcrumb } from "@sisyphos-ui/react";
```

## Framework usage

### React 18+

```tsx
import { Breadcrumb } from "@sisyphos-ui/react";

export const Crumbs = () => (
  <Breadcrumb
    items={[
      { label: "Home", href: "/" },
      { label: "Projects", href: "/projects" },
      { label: "Sisyphos UI" },
    ]}
  />
);
```

### Vue 3+

```vue
<script setup lang="ts">
import { Breadcrumb } from "@sisyphos-ui/vue";

const items = [
  { label: "Home", href: "/" },
  { label: "Projects", href: "/projects" },
  { label: "Sisyphos UI" },
];
</script>

<template>
  <Breadcrumb :items="items" />
</template>
```

### Angular 17+

```ts
import { Component } from "@angular/core";
import { Breadcrumb } from "@sisyphos-ui/angular";

@Component({
  selector: "app-crumbs",
  standalone: true,
  imports: [Breadcrumb],
  template: `<sui-breadcrumb [items]="items" />`,
})
export class CrumbsComponent {
  items = [
    { label: "Home", href: "/" },
    { label: "Projects", href: "/projects" },
    { label: "Sisyphos UI" },
  ];
}
```

## Examples

### Default

```tsx
import { Breadcrumb } from "@sisyphos-ui/react";

export function Example() {
  return (
    <Breadcrumb
      items={[
        { label: "Home",       href: "/" },
        { label: "Docs",       href: "/docs" },
        { label: "Components", href: "/docs/components" },
        { label: "Breadcrumb" },
      ]}
    />
  );
}
```

### Collapsed middle

Set `maxItems` with `itemsBeforeCollapse` + `itemsAfterCollapse` to keep the trail compact on deep hierarchies.

```tsx
import { Breadcrumb } from "@sisyphos-ui/react";

export function Example() {
  return (
    <Breadcrumb
      maxItems={4}
      itemsBeforeCollapse={1}
      itemsAfterCollapse={2}
      items={[
        { label: "Home", href: "#" },
        { label: "Workspaces", href: "#" },
        { label: "Acme", href: "#" },
        { label: "Projects", href: "#" },
        { label: "Website redesign", href: "#" },
        { label: "Tasks", href: "#" },
        { label: "Q4 roadmap" },
      ]}
    />
  );
}
```

### With icons

Each item accepts an `icon` ReactNode.

```tsx
import { Breadcrumb } from "@sisyphos-ui/react";

const FolderIcon = () => (
  <svg viewBox="0 0 24 24" width={14} height={14} aria-hidden="true">
    <path fill="currentColor" d="M10 4H2v16h20V6H12l-2-2z" />
  </svg>
);

export function Example() {
  return (
    <Breadcrumb
      items={[
        { label: "Files", href: "#", icon: <FolderIcon /> },
        { label: "Workspace", href: "#", icon: <FolderIcon /> },
        { label: "Design", href: "#", icon: <FolderIcon /> },
        { label: "components.fig" },
      ]}
    />
  );
}
```

### Custom separator

Pass any ReactNode via `separator`.

```tsx
import { Breadcrumb } from "@sisyphos-ui/react";

export function Example() {
  return (
    <Breadcrumb
      separator={<span aria-hidden="true">›</span>}
      items={[
        { label: "Dashboard", href: "#" },
        { label: "Reports", href: "#" },
        { label: "Revenue", href: "#" },
        { label: "Q3 2026" },
      ]}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **items** (required) | `BreadcrumbItem[]` | — | Ordered entries (`label`, optional `href`, `onClick`, `icon`, `key`). The last item is treated as the current page. |
| separator | `ReactNode` | `"/"` | Custom separator rendered between items. |
| maxItems | `number` | — | Collapses middle items into an ellipsis when the total exceeds this count. |
| itemsBeforeCollapse | `number` | `1` | Items kept before the ellipsis when collapsing. |
| itemsAfterCollapse | `number` | `1` | Items kept after the ellipsis when collapsing. |

## Keyboard interactions

- **Tab** — Moves focus through the breadcrumb links in trail order.
- **Enter** — Activates the focused link (or button, for `onClick`-only items).

## Accessibility notes

- Rendered inside a `<nav aria-label="breadcrumb">` landmark wrapping an ordered list.
- The last item is the current page — rendered as plain text with `aria-current="page"`, never as a link.
- Separators and the collapse ellipsis are `aria-hidden="true"`, so screen readers announce only the trail items.
- Middle items collapse behind `maxItems` without losing the first / last entries (`itemsBeforeCollapse` / `itemsAfterCollapse`).

<!-- exports: { "Breadcrumb": "@sisyphos-ui/react" } -->