# Breadcrumb

> A React breadcrumb that shows where you are, folds the middle of long paths and gives phones a back link.

- Type: React component (Navigation)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add breadcrumb`
- Docs: https://wingo-ui.com/components/breadcrumb

## Interaction

Click a crumb to go up a level; the current page is plain text. When the row gets too narrow the middle entries fold into a “…” button, one by one, and come back as soon as there is room; click it (or focus it and press Enter, Space or ArrowDown) for a menu of the hidden pages, walked with the arrow keys and closed with Escape. A crumb with siblings has a small chevron that opens a menu of them with the current one checked. Labels longer than maxItemWidth truncate; hover or focus them (long press on touch) to read the full text. When the trail changes, new crumbs slide in and the others glide into place. Below 640px it becomes one “‹ Parent” back link with a 44px target (or first / … / current), and every menu opens as a bottom action sheet.

## Installation

```bash
npx wingo-ui@latest add breadcrumb
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/breadcrumb` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/breadcrumb.tsx`

npm dependencies: `npm i @radix-ui/react-slot lucide-react motion`

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [useOverflowItems](https://wingo-ui.com/components/use-overflow-items) ([Markdown](https://wingo-ui.com/components/use-overflow-items.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { Home } from "lucide-react"
import { Breadcrumb, type BreadcrumbEntry } from "@/components/ui/breadcrumb"
import type { NavItem } from "@/lib/navigation"

const clients: NavItem[] = [
  { label: "Northwind Tech Inc.", href: "/clients/42" },
  { label: "Summit Logistics", href: "/clients/57" },
  { label: "Anna Price Consulting", href: "/clients/63" },
]

export function InvoiceTrail() {
  const items: BreadcrumbEntry[] = [
    { label: "Home", href: "/", icon: <Home /> },
    { label: "Clients", href: "/clients" },
    { label: "Northwind Tech Inc.", href: "/clients/42", menu: clients },
    { label: "Invoices", href: "/clients/42/invoices" },
    { label: "#2026-0412" },
  ]

  return (
    <Breadcrumb
      items={items}
      labels={{
        more: "Show the hidden pages",
        back: (label) => `Up to ${label}`,
      }}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items?` | `BreadcrumbEntry[]` |  | { id?: string; label: ReactNode; href?: string; icon?: ReactNode; onSelect?: (event) => void; menu?: NavItem[]; textValue?: string }. Root first; the last entry is the current page. Middle entries without href are plain text (a button with onSelect). menu adds a sibling switcher after the label. An empty label with an icon renders an icon-only crumb named by textValue (read by screen readers, shown in a tooltip). Leave items out to hand-build the trail from the parts. |
| `children?` | `ReactNode` |  | A hand-built trail from the shadcn-compatible parts (BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis), rendered inside the <nav> when items is not set. |
| `separator?` | `"chevron" \| "slash" \| "dot" \| "arrow" \| ReactNode` | `"chevron"` | The glyph between crumbs: ChevronRight, “/”, “·”, ArrowRight or any node. Chevron and arrow flip in right-to-left layouts. |
| `size?` | `"sm" \| "md"` | `"md"` | Text 13 / 14px with 4 / 6px gaps. Icons stay 14px. |
| `maxItemWidth?` | `number` | `200` | px. Longer labels truncate with an ellipsis and show the full text in a tooltip. |
| `collapse?` | `"auto" \| "never"` | `"auto"` | auto: while the row does not fit, entries fold into “…” from the second one onward; the first and the current page always stay. never: the trail wraps onto more lines. |
| `maxItems?` | `number` | `0` | Also fold when there are more entries than this, keeping itemsBeforeCollapse at the start and itemsAfterCollapse at the end. 0 folds only when the row does not fit. Ignored when it is smaller than itemsBeforeCollapse + itemsAfterCollapse + 1. |
| `itemsBeforeCollapse?` | `number` | `1` | Entries kept at the start when folding by maxItems. |
| `itemsAfterCollapse?` | `number` | `2` | Entries kept at the end when folding by maxItems (the parent and the current page). |
| `mobileVariant?` | `"back" \| "collapse" \| "full"` | `"back"` | What phones get, switched with CSS so the server HTML is right. back: one “‹ Parent” link to the second-to-last entry (falls back to collapse when that entry has no href). collapse: first / … / current. full: the desktop trail. |
| `mobileBreakpoint?` | `"sm" \| "md" \| "always"` | `"sm"` | Where the phone form takes over: below 640px (sm), below 768px (md), or at every width (always, for narrow side panels). |
| `animate?` | `boolean` | `true` | When the trail changes, new crumbs slide in from the side and the rest glide into place; leaving ones fade. Under reduced motion it only fades. |
| `responsive?` | `boolean` | `true` | The “…” and sibling menus open as bottom action sheets below 768px. false keeps the dropdown everywhere. |
| `linkComponent?` | `(props: LinkComponentProps) => ReactNode` |  | The router link every crumb renders through (next/link's Link). Default: the LinkProvider's, else a plain <a>. |
| `labels?` | `{ navigation?: string; more?: string; back?: (label: string) => string; siblings?: (label: string) => string; cancel?: string }` |  | Accessible names and sheet text. Defaults: navigation "Breadcrumb", more "Show hidden pages", back l => "Back to " + l, siblings l => "Switch " + l, cancel "Cancel". |
| `classNames?` | `Partial<Record<"list" \| "item" \| "link" \| "page" \| "separator" \| "ellipsis" \| "back", string>>` |  | Extra classes for the inner parts; className styles the <nav>. |

## Parts

### BreadcrumbList (component)

The <ol> that lays out a hand-built trail in one row. Takes every <ol> prop.

### BreadcrumbItem (component)

One crumb's <li>; put a BreadcrumbLink or a BreadcrumbPage inside.

### BreadcrumbLink (component)

A crumb link rendered through NavLink. asChild styles your own element (a router Link); without href it renders a button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href?` | `string` |  | Where the crumb goes. Leave it out for a button. |
| `asChild?` | `boolean` | `false` | Renders your single child with the crumb's look. |
| `linkComponent?` | `LinkComponent` |  | A router link component, like next/link, used for the anchor. |

### BreadcrumbPage (component)

The current page: plain text with aria-current="page", truncated with the same max width as the links.

### BreadcrumbSeparator (component)

An aria-hidden <li role="presentation"> with the glyph between crumbs. Pass children for a custom glyph.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind?` | `"chevron" \| "slash" \| "dot" \| "arrow"` |  | The glyph; defaults to the Breadcrumb's separator. |

### BreadcrumbEllipsis (component)

The “…” button for folded crumbs. With items it opens a menu of those pages (a bottom sheet on phones); without items it is the bare glyph.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items?` | `BreadcrumbEntry[]` |  | The hidden pages listed in the menu. |
| `open?` | `boolean` |  | Controlled menu state. |
| `onOpenChange?` | `(open: boolean) => void` |  | Called when the menu opens or closes. |
| `responsive?` | `boolean` |  | A bottom action sheet below 768px instead of a dropdown. Defaults to the Breadcrumb's responsive. |

### BreadcrumbEntry (type)

One entry of items: { id?, label, href?, icon?, onSelect?, menu?, textValue? }.

### BreadcrumbProps (type)

The props of Breadcrumb, for wrappers that build the trail from your router.

## Examples

- **Separators**: chevron, slash, dot and arrow; chevron and arrow flip in right-to-left layouts.
- **maxItems on a file path**: maxItems={4} keeps the first folder and the last two entries; the rest waits in the “…” menu. In a narrow column the width fold hides more.
- **Sibling switchers**: A chevron after a crumb opens its siblings, the current one checked.
- **Phone forms**: Below 640px: one “‹ Parent” link (back) or first / … / current (collapse). Shown here at every width.
- **Long labels**: Labels past maxItemWidth truncate and show the full text in a tooltip.
- **Sizes**: sm (13px) and md (14px), with an icon-only Home crumb or an icon and a label.
- **Built from parts**: shadcn-compatible parts for hand-built trails: List, Item, Link, Page, Separator, Ellipsis.

## See also

- [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md))
- [Dropdown Menu](https://wingo-ui.com/components/dropdown-menu) ([Markdown](https://wingo-ui.com/components/dropdown-menu.md))
- [useOverflowItems](https://wingo-ui.com/components/use-overflow-items) ([Markdown](https://wingo-ui.com/components/use-overflow-items.md))
- [Steps](https://wingo-ui.com/components/steps) ([Markdown](https://wingo-ui.com/components/steps.md))

---

Canonical: https://wingo-ui.com/components/breadcrumb
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt