Navigation · astro-ui · Breadcrumb

Breadcrumb

Semantic breadcrumb trail — CSS separators, icons, ellipsis, pill, composed items.

Breadcrumb renders a <nav aria-label> of links — a flat flex container, no list markup. The current page is a non-link span with aria-current=“page”; separators are drawn in CSS pseudo-elements. Pass items for data-driven trails (with optional icon and ellipsis fields) or omit items and author composed <span> children for badges, avatars, dropdown triggers, and buttons.

← All components

Features

  • Semantic nav structure, flat span items — no list markup
  • aria-current="page" on the current item
  • Separators drawn in CSS: slash, chevron, double-chevron, dot, custom
  • icon + ellipsis item fields for rich trails
  • Composed slot mode for badges, avatars, dropdowns, buttons
  • Pill style for frames, headers, and toolbars
  • 3 sizes; hidden items for responsive trimming

Usage

---
import { Breadcrumb } from "astro-ui";
---

<Breadcrumb
  ariaLabel="Breadcrumb"
  items={[
    { href: "/", label: "Home" },
    { href: "/components/", label: "Components" },
    { label: "Button" },
  ]}
/>

Demos

Basic

<Breadcrumb
  items={[
    { href: "/", label: "Home" },
    { href: "/components/", label: "Components" },
    { label: "Button" },
  ]}
/>

Chevron separator

<Breadcrumb separator="chevron"
  items={[
    { href: "/", label: "Home" },
    { label: "Docs" },
  ]}
/>

Breadcrumb with dropdown menu

<Breadcrumb ariaLabel="Breadcrumb with collapsed path">
  <span class="aui-breadcrumb__item">
    <a class="aui-breadcrumb__link" href="/">Home</a>
  </span>
  <span class="aui-breadcrumb__item">
    <Popover id="bc-menu" triggerLabel="Show hidden path segments">
      <span slot="trigger">
        <span class="aui-breadcrumb__ellipsis" aria-hidden="true">…</span>
      </span>
      <span slot="content" class="docs-breadcrumb-menu">
        <a href="#">Documentation</a>
        <a href="#">Themes</a>
        <a href="#">GitHub</a>
      </span>
    </Popover>
  </span>
  <span class="aui-breadcrumb__item">
    <a class="aui-breadcrumb__link" href="#">Components</a>
  </span>
  <span class="aui-breadcrumb__item">
    <span class="aui-breadcrumb__current" aria-current="page">Breadcrumb</span>
  </span>
</Breadcrumb>

<style is:global>
  /* Tighten the popover trigger to the breadcrumb line; style the panel links. */
  .aui-breadcrumb .aui-popover__trigger { padding: 0.125rem 0.25rem; border-radius: var(--ui-radius-sm); }
  .docs-breadcrumb-menu { display: grid; min-inline-size: 10rem; }
  .docs-breadcrumb-menu a { padding: 0.25rem 0.5rem; color: var(--ui-foreground); font-size: var(--ui-text-sm); text-decoration: none; border-radius: var(--ui-radius-sm); }
  .docs-breadcrumb-menu a:hover { background: var(--ui-muted); }
</style>

Custom slash separator

Custom glyphs — double slash and bullet — via separator="custom".

<Breadcrumb
  separator="custom"
  style="--aui-breadcrumb-separator: '//'"
  items={[
    { href: "/", label: "usr" },
    { href: "#", label: "local" },
    { label: "bin" },
  ]}
/>

Ellipsis for long paths

<Breadcrumb
  items={[
    { href: "/", label: "Home" },
    { ellipsis: true, label: "More" },
    { href: "#", label: "Components" },
    { label: "Breadcrumb" },
  ]}
/>

Icons for each item

<Breadcrumb separator="chevron"
  items={[
    { href: "/", label: "Home", icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M9 22V12h6v10"/></svg>' },
    { href: "#", label: "Library", icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></svg>' },
    { label: "Breadcrumb", icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M15 2v5h5"/></svg>' },
  ]}
/>

Double chevron separators

<Breadcrumb separator="chevrons"
  items={[
    { href: "/", label: "Dashboard" },
    { href: "#", label: "Resources" },
    { label: "Documentation" },
  ]}
/>

Pill-style breadcrumb inside frame

<Breadcrumb
  pill
  separator="chevron"
  items={[
    { href: "/", label: "Home", icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M9 22V12h6v10"/></svg>' },
    { href: "#", label: "Products" },
    { label: "Checkout" },
  ]}
/>

Home icon item

<Breadcrumb
  items={[
    { href: "/", label: "Home", icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M9 22V12h6v10"/></svg>' },
    { href: "#", label: "Products" },
    { label: "Checkout" },
  ]}
/>

Badge with count

<Breadcrumb ariaLabel="Mailbox">
  <span class="aui-breadcrumb__item">
    <a class="aui-breadcrumb__link" href="#">
      Inbox
      <Badge variant="destructive" size="sm" ariaLabel="3 unread messages" style="min-inline-size: 1.25rem">3</Badge>
    </a>
  </span>
  <span class="aui-breadcrumb__item">
    <a class="aui-breadcrumb__link" href="#">Labels</a>
  </span>
  <span class="aui-breadcrumb__item">
    <span class="aui-breadcrumb__current" aria-current="page">Important</span>
  </span>
</Breadcrumb>

Button-style breadcrumb

<Breadcrumb ariaLabel="Help center">
  <span class="aui-breadcrumb__item">
    <Button variant="outline" size="xs" shape="rounded" aria-label="Home">
      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><path d="M9 22V12h6v10"/></svg>
    </Button>
  </span>
  <span class="aui-breadcrumb__item">
    <a class="aui-breadcrumb__link" href="#">Help Center</a>
  </span>
  <span class="aui-breadcrumb__item">
    <span class="aui-breadcrumb__current" aria-current="page">Getting Started</span>
  </span>
</Breadcrumb>

Breadcrumb inside card

<Card size="sm">
  <Breadcrumb
    separator="chevron"
    items={[
      { href: "/", label: "Home" },
      { href: "#", label: "Products" },
      { label: "Checkout" },
    ]}
  />
</Card>

API

Props

PropTypeDefaultDescription
itemsBreadcrumbItem[][]Trail: { href?, label, hidden?, icon?, ellipsis? }. Last item without href = current page. Omit to author composed items in the default slot.
ariaLabelstring"Breadcrumb"Name for the nav landmark.
separator"slash" | "chevron" | "chevrons" | "dot" | "custom""slash"Separator glyph (CSS-drawn); custom reads --aui-breadcrumb-separator.
pillbooleanfalseRenders the trail in a muted pill.
size"sm" | "md" | "lg""md"Text scale.
classstring—Merged via cn(); Tailwind classes welcome.
idstring—Element id.

Accessibility

Implemented accessibility features — semantics, ARIA wiring, and keyboard behavior that ship with the component.

  • Wrapped in <nav> with an aria-label so it's a navigable landmark
  • aria-current="page" on the last item announces the current location
  • Separators are CSS pseudo-elements — never read by screen readers

FAQ

Why no separator markup?

Separators are pseudo-elements, so screen readers announce only the real items — no repeated 'slash' noise.

How do I add badges or avatars to items?

Omit items and author the trail: <Breadcrumb><span class="aui-breadcrumb__item">…</span></Breadcrumb>. Compose any astro-ui component inside the item spans; the same separator and typography styles apply.

How do I collapse a long path?

Set ellipsis: true on a middle item to render a presentational …, or compose a Popover trigger inside an item so users can open the hidden segments from the ellipsis.

Changelog

Version history mentioning Breadcrumb.

v0.1.0 — 2026-11-11
added
  • Navigation (7): Tabs, Breadcrumb, Pagination, Stepper, Tree, Navbar, Sidebar.