Skip to content

Breadcrumbs

The path from the top of the site to the current page, as links. Use BreadcrumbItem for each step; the last one is the current page.

Navigationv0.1.0experimentalWCAG 2.2 AAView spec
import { BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

// The last item has no href: it is the current page.
export default function BreadcrumbsBasicExample() {
  return (
    <div className="flex w-full justify-center">
      <Breadcrumbs>
        <BreadcrumbItem href="/">Home</BreadcrumbItem>
        <BreadcrumbItem href="/projects">Projects</BreadcrumbItem>
        <BreadcrumbItem>Website redesign</BreadcrumbItem>
      </Breadcrumbs>
    </div>
  );
}

Installation

npx rdloom add breadcrumbs

Copies the source into src/components/rdloom. Edit it freely: rdloom upgrade merges later versions into your changes. It needs react-aria-components; add --install to install them.

Use another registry client
npx shadcn@latest add https://rdloom.vimalbhatt.com/r/breadcrumbs.json

Works, but without upgrade tracking.

Usage

import { BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

<div className="flex w-full justify-center">
  <Breadcrumbs>
    <BreadcrumbItem href="/">Home</BreadcrumbItem>
    <BreadcrumbItem href="/projects">Projects</BreadcrumbItem>
    <BreadcrumbItem>Website redesign</BreadcrumbItem>
  </Breadcrumbs>
</div>

With icon

import { BreadcrumbItem, Breadcrumbs, HomeIcon } from "@rdloom/react";

// An icon before the first step. The text still names it, so the icon is decorative.
export default function BreadcrumbsWithIconExample() {
  return (
    <div className="flex w-full justify-center">
      <Breadcrumbs>
        <BreadcrumbItem href="/" icon={<HomeIcon />}>
          Home
        </BreadcrumbItem>
        <BreadcrumbItem href="/invoices">Invoices</BreadcrumbItem>
        <BreadcrumbItem>INV-2041</BreadcrumbItem>
      </Breadcrumbs>
    </div>
  );
}

Slash separator

import { BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

export default function BreadcrumbsSlashSeparatorExample() {
  return (
    <div className="flex w-full justify-center">
      <Breadcrumbs separator="slash">
        <BreadcrumbItem href="/">Home</BreadcrumbItem>
        <BreadcrumbItem href="/settings">Settings</BreadcrumbItem>
        <BreadcrumbItem>Billing</BreadcrumbItem>
      </Breadcrumbs>
    </div>
  );
}

Custom separator

import { BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

const dot = <span className="size-1 rounded-full bg-current" />;

// Any mark can go between steps. Give each item the same `separator` to keep the trail even.
export default function BreadcrumbsCustomSeparatorExample() {
  return (
    <div className="flex w-full justify-center">
      <Breadcrumbs>
        <BreadcrumbItem href="/" separator={dot}>
          Home
        </BreadcrumbItem>
        <BreadcrumbItem href="/reports" separator={dot}>
          Reports
        </BreadcrumbItem>
        <BreadcrumbItem>Quarterly sales</BreadcrumbItem>
      </Breadcrumbs>
    </div>
  );
}

Collapsed

import { BreadcrumbEllipsis, BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

// The middle of a long trail sits behind one button. Its steps open as a menu of links.
export default function BreadcrumbsCollapsedExample() {
  return (
    <div className="flex w-full justify-center">
      <Breadcrumbs label="You are here">
        <BreadcrumbItem href="/">Home</BreadcrumbItem>
        <BreadcrumbEllipsis
          items={[
            { label: "Documentation", href: "/docs" },
            { label: "Components", href: "/docs/components" },
            { label: "Forms", href: "/docs/components/forms" },
          ]}
        />
        <BreadcrumbItem href="/docs/components/forms/inputs">Inputs</BreadcrumbItem>
        <BreadcrumbItem>Number field</BreadcrumbItem>
      </Breadcrumbs>
    </div>
  );
}

Long trail

import { BreadcrumbItem, Breadcrumbs } from "@rdloom/react";

// Without a collapsed middle, a long trail wraps onto the next line instead of overflowing.
export default function BreadcrumbsLongTrailExample() {
  return (
    <div className="flex w-full justify-center">
      <div className="w-72">
        <Breadcrumbs label="You are here">
          <BreadcrumbItem href="/">Home</BreadcrumbItem>
          <BreadcrumbItem href="/docs">Documentation</BreadcrumbItem>
          <BreadcrumbItem href="/docs/components">Components</BreadcrumbItem>
          <BreadcrumbItem href="/docs/components/forms">Forms</BreadcrumbItem>
          <BreadcrumbItem href="/docs/components/forms/inputs">Inputs</BreadcrumbItem>
          <BreadcrumbItem>Number field</BreadcrumbItem>
        </Breadcrumbs>
      </div>
    </div>
  );
}

API Reference

Defined by the spec. Components also accept the props of the React Aria component they wrap.

PropTypeDefault
childrenrequired

BreadcrumbItem elements, from the top level down to the current page.

nodenone
label

Accessible name of the navigation landmark. Translate it for other languages.

string"Breadcrumbs"
separator

The mark between steps. Use BreadcrumbItem's own `separator` prop for any other mark.

"chevron" | "slash""chevron"
isDisabled

Disables every link in the trail.

booleanfalse

Accessibility

Role navigation, WCAG 2.2 AA. Tested with axe and keyboard tests; screen reader checks are in the audit checklist.

Keyboard

  • Tab moves between the links
  • Enter follows a link

Screen readers announce

  • Announced as a navigation landmark named Breadcrumbs, with a list of N items
  • The final item is announced as the current page

What your code must do

  • A navigation landmark with an accessible name, containing an ordered list of links
  • The last item is the current page: aria-current="page", and it cannot be followed (it has no href and is aria-disabled)
  • Separators are decorative (aria-hidden), so they are not read out
  • Links have a visible focus ring
  • A collapsed trail keeps the hidden steps in a menu, reached by a button that is named (for example "Show hidden pages") and opens with Enter or Space

Guidelines

Use it when

  • Sites or apps with more than two levels of hierarchy
  • Telling people where they are and how to go back up

Avoid it when

  • A flat site with one level: no trail is needed
  • Showing the steps someone has taken: use a stepper

Don't

  • Making the current page a link to itself
  • Using breadcrumbs instead of the main navigation
  • Hiding the trail from screen readers with aria-hidden

Design tokens

The semantic tokens this component uses. Change them once and every component follows; see Design tokens.

  • --rd-color-text-default
  • --rd-color-text-muted
  • --rd-color-focus-ring
  • --rd-radius-control