Breadcrumb

A trail of links showing the current page's location in a navigational hierarchy.

Usage

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from '@appica/ui-react/breadcrumb'

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/ui/components">Components</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Breadcrumb is a small set of semantic primitives — there's no hidden state, so you lay the trail out yourself. Every part lives under @appica/ui-react/breadcrumb:

Breadcrumb — the <nav aria-label="breadcrumb"> landmark that wraps the trail.
BreadcrumbList — the ordered list (<ol>) of crumbs; handles wrapping and spacing.
BreadcrumbItem — one <li>, holding a link (or a collapsed menu).
BreadcrumbLink — a crumb. By default it renders an <a>; mark the current page with active and it becomes a non-interactive <span> with aria-current="page".
BreadcrumbSeparator — the divider between crumbs (a chevron by default; pass children to override).
BreadcrumbEllipsis — a "…" placeholder for crumbs collapsed out of a long trail.

BreadcrumbLink uses Base UI's useRender, so you can project it onto your router's link with render — e.g. a Next.js Link — without losing the styling or the active state.

Reach for a Breadcrumb to show where the current page sits in a hierarchy. For switching between sibling views, use Navigation or Tabs; for a menu of links opened from a button, use a Dropdown Menu.

Examples

Basic

A trail of links ending in the current page. Give every link before the last an href; mark the final crumb active so it renders as plain, non-focusable text with aria-current="page".

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbBasic() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

With icons

Drop an icon straight inside a BreadcrumbLink — it's sized and spaced automatically next to the label. A leading icon on the Home crumb is a common space-saver.

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'
import { Home, Folder, FileText } from '@appica/icons-react'

export default function BreadcrumbIcons() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">
            <Home />
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">
            <Folder />
            Projects
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>
            <FileText />
            Roadmap
          </BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

Custom separators

BreadcrumbSeparator renders a chevron by default. Pass it children to swap in anything — a slash, a dot, or your own icon. The separator is decorative (aria-hidden), so it's skipped by screen readers.

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbSeparators() {
  return (
    <div className="flex flex-col gap-5">
      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Home</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Docs</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>/</BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>

      <Breadcrumb>
        <BreadcrumbList>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Home</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>
            <span className="bg-foreground-muted size-0.75 rounded-full" />
          </BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink href="#!">Docs</BreadcrumbLink>
          </BreadcrumbItem>
          <BreadcrumbSeparator>
            <span className="bg-foreground-muted size-0.75 rounded-full" />
          </BreadcrumbSeparator>
          <BreadcrumbItem>
            <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
          </BreadcrumbItem>
        </BreadcrumbList>
      </Breadcrumb>
    </div>
  )
}

Soft badges

Project each BreadcrumbLink onto a soft Badge with render for a pill-style trail. The Badge's soft variant has built-in breadcrumb support — idle crumbs render muted like a plain link, brighten on hover, and the active crumb gains a bordered, filled pill. Project the Badge onto an <a> (render={<a />}) so the hover background animates.

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'
import { Badge } from '@appica/ui-react/badge'
import { Home, Components } from '@appica/icons-react'

export default function BreadcrumbBadges() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!" render={<Badge variant="soft" render={<a />} />}>
            <Home data-icon="start" />
            Home
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!" render={<Badge variant="soft" render={<a />} />}>
            <Components data-icon="start" />
            Library
          </BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active render={<Badge variant="soft" />}>
            <Components data-icon="start" />
            Component
          </BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

Collapsed trail

When a trail is too long, collapse the middle crumbs behind a menu. Wrap a Dropdown Menu in the BreadcrumbItem, project the trigger onto the BreadcrumbEllipsis, and list the hidden pages as DropdownMenuLinkItems. The ellipsis carries an sr-only "More" label, so the trigger stays named for assistive tech.

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from '@appica/ui-react/breadcrumb'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuLinkItem,
} from '@appica/ui-react/dropdown-menu'

export default function BreadcrumbCollapsed() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <DropdownMenu>
            <DropdownMenuTrigger className="text-foreground-muted hover:text-foreground-intense outline-ring hover:bg-background-muted data-popup-open:bg-background-muted data-popup-open:text-foreground-intense rounded-2xs flex size-6 items-center justify-center transition">
              <BreadcrumbEllipsis />
            </DropdownMenuTrigger>
            <DropdownMenuContent align="start">
              <DropdownMenuLinkItem href="#!">Documentation</DropdownMenuLinkItem>
              <DropdownMenuLinkItem href="#!">Components</DropdownMenuLinkItem>
              <DropdownMenuLinkItem href="#!">Themes</DropdownMenuLinkItem>
            </DropdownMenuContent>
          </DropdownMenu>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="#!">Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Collapsed</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

Router links

For client-side routing, project a BreadcrumbLink onto your framework's link via render — here a Next.js Link. The crumb keeps its styling and aria-current handling while the router owns navigation.

import Link from 'next/link'
import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbSeparator,
} from '@appica/ui-react/breadcrumb'

export default function BreadcrumbLinks() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/ui/components/react/breadcrumb" />}>Home</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink render={<Link href="/ui/components/react/breadcrumb" />}>Components</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink active>Breadcrumb</BreadcrumbLink>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The trail flows from the right and the default chevron separator mirrors to point the other way. For setup details and caveats, see the RTL guide.

API reference

Breadcrumb is a set of styled HTML elements. Each part forwards every remaining prop to its underlying element (nav, ol, li, a, span), so any native attribute works here — the tables below list the Appica additions and the most common props.

The navigation landmark. Renders a <nav aria-label="breadcrumb">.

Prop	Type	Default	Description
`children`	`ReactNode`	—	A single `BreadcrumbList`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

BreadcrumbList

The ordered list of crumbs. Renders an <ol> that wraps and spaces its items.

Prop	Type	Default	Description
`children`	`ReactNode`	—	`BreadcrumbItem`s and `BreadcrumbSeparator`s.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

BreadcrumbItem

One crumb's <li> wrapper.

Prop	Type	Default	Description
`children`	`ReactNode`	—	A `BreadcrumbLink`, ellipsis, or menu.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

BreadcrumbLink

A crumb link. Built on Base UI's useRender; renders an <a> unless active (then a <span>), or use render to project it onto another element.

Prop	Type	Default	Description
`active`	`boolean`	`false`	Mark the current page. Renders a non-interactive `<span>` with `aria-current="page"`.
`disabled`	`boolean`	`false`	Make the link non-interactive and dimmed.
`render`	`ReactElement \| (props, state) => ReactElement`	—	Render as your own element (e.g. a router `Link`).
`href`	`string`	—	Navigation target (when rendered as an `<a>`).
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

BreadcrumbSeparator

The divider between crumbs. Decorative (aria-hidden); renders a chevron unless you pass children.

Prop	Type	Default	Description
`children`	`ReactNode`	chevron icon	Override the separator with your own text or icon.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

BreadcrumbEllipsis

A "…" placeholder for collapsed crumbs. Decorative, with an sr-only "More" label.

Prop	Type	Default	Description
`children`	`ReactNode`	ellipsis dots	Override the placeholder mark.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

Breadcrumb renders a <nav> with aria-label="breadcrumb", so it's exposed as a named navigation landmark.
The current page (active) is a <span> with aria-current="page" — not a link — so it isn't announced as clickable.
Separators and the ellipsis are aria-hidden/role="presentation"; the ellipsis keeps an sr-only "More" label for the collapse trigger.
disabled links set aria-disabled and drop out of the tab order.
Crumbs are keyboard-focusable links by default and inherit the page's focus-ring styling.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback