# Breadcrumb

## Overview

A hierarchical navigation trail showing the user's current position in the application's page structure. Rendered in the `Header` component via the `breadcrumbs` prop. Each item in the chain can optionally be a clickable link.

---

## When to Use

- In the application header to show the current page's position in the hierarchy
- In pages with deep navigation structures (Dashboard > Reports > Q4 2024)

---

## Anatomy

```
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/home">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Current Page</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

---

## Sub-Components

| Component             | Description                                            |
| --------------------- | ------------------------------------------------------ |
| `Breadcrumb`          | Root wrapper (renders `<nav aria-label="breadcrumb">`) |
| `BreadcrumbList`      | Ordered list of breadcrumb items                       |
| `BreadcrumbItem`      | Individual breadcrumb item                             |
| `BreadcrumbLink`      | Clickable link item                                    |
| `BreadcrumbPage`      | Non-linked current page item                           |
| `BreadcrumbSeparator` | Visual separator between items (default: `/`)          |
| `BreadcrumbEllipsis`  | Collapsed items indicator for long chains              |

---

## Examples

### Via Header (Recommended)

```tsx
<Header
  breadcrumbs={[
    { label: 'Dashboard', href: '/dashboard', icon: <Home className="w-4 h-4" /> },
    { label: 'Users', href: '/users' },
    { label: 'Ariel Santos' }, // No href = current page
  ]}
/>
```

### Manual Composition

```tsx
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbPage,
} from 'xertica-ui/ui';

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/home">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/settings">Settings</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Profile</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>;
```

---

## AI Rules

- The **last item** in the breadcrumb is always the current page and must use `<BreadcrumbPage>` (not `<BreadcrumbLink>`).
- Prefer using the `breadcrumbs` prop on `<Header>` — it automatically handles all the composition for you.
- Always add a `<BreadcrumbSeparator>` between every two items.

---

## Related Components

- [`Header`](./header.md) — Primary context for Breadcrumb usage
- [`NavigationMenu`](./navigation-menu.md) — For horizontal top-level navigation