Skip to content
Browse documentation
whisk/ui

Breadcrumb

Show the current location in a hierarchy.

Overview

Breadcrumb shows the current location within a hierarchy. It combines a labelled navigation landmark, an ordered list of ancestor links, and a non-interactive current-page item.

Coming from another library?
Use BreadcrumbCurrent for the current page, not BreadcrumbPage or BreadcrumbCurrentLink. Add BreadcrumbSeparator between items yourself.

Use when

You need to show the current location within a page hierarchy.

Use instead

Use Tabs for views in the same context or a progress indicator for task progress.

Usage

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbCurrent>Atlas</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Examples

Variants

Use plain for a quiet path and underline when ancestor links need a stronger affordance.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
  Stack,
} from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Breadcrumb variant="plain">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
  <Breadcrumb variant="underline">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
</Stack>

Sizes

Set size to match the surrounding interface density.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
  Stack,
} from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Breadcrumb size="sm">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
  <Breadcrumb size="md">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
  <Breadcrumb size="lg">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
</Stack>

Separator

Render custom separator content with BreadcrumbSeparator. Separators stay decorative.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>/</BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbLink href="#atlas">Atlas</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>/</BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Icon

Put a decorative icon inside BreadcrumbLink when it helps people recognise the destination.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";
import { HomeIcon } from "@smoothie-framework/whisk-react/icons";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#home">
        <HomeIcon size="sm" />
        Home
      </BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Menu

Use a labelled menu trigger to switch to a sibling page.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#home">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <BreadcrumbLink as="button">Projects</BreadcrumbLink>
        </DropdownMenuTrigger>
        <DropdownMenuContent aria-label="Projects">
          <DropdownMenuItem asChild>
            <a href="#atlas">Atlas</a>
          </DropdownMenuItem>
          <DropdownMenuItem asChild>
            <a href="#northstar">Northstar</a>
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Ellipsis

A bare ellipsis removes destinations for everyone; pair it with a menu unless the hidden levels are reachable elsewhere.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <BreadcrumbEllipsis as="button" aria-label="Show hidden pages" />
        </DropdownMenuTrigger>
        <DropdownMenuContent aria-label="Hidden pages">
          <DropdownMenuItem asChild>
            <a href="#workspace">Workspace</a>
          </DropdownMenuItem>
          <DropdownMenuItem asChild>
            <a href="#reports">Reports</a>
          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="#atlas">Atlas</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

From data

Map path data to items, render separators between them, and mark only the last item as current.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";

const path = [
  { href: "#projects", label: "Projects" },
  { href: "#atlas", label: "Atlas" },
  { href: "#settings", label: "Settings" },
];

<Breadcrumb>
  <BreadcrumbList>
    {path.flatMap((item, index) => [
      index > 0 ? <BreadcrumbSeparator key={`${item.href}-separator`} /> : null,
      <BreadcrumbItem key={item.href}>
        {index === path.length - 1 ? (
          <BreadcrumbCurrent>{item.label}</BreadcrumbCurrent>
        ) : (
          <BreadcrumbLink href={item.href}>{item.label}</BreadcrumbLink>
        )}
      </BreadcrumbItem>,
    ])}
  </BreadcrumbList>
</Breadcrumb>

Routing

Use asChild with a router link that renders an anchor and forwards anchor props.

import { Link as RouterLink } from "react-router-dom";
import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink asChild>
        <RouterLink to="/projects">Projects</RouterLink>
      </BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbCurrent>Settings</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

RTL

Breadcrumb order follows the document direction. Directional separator icons do not mirror automatically.

import {
  Breadcrumb,
  BreadcrumbCurrent,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbSeparator,
} from "@smoothie-framework/whisk-react";
import { ChevronLeftIcon } from "@smoothie-framework/whisk-react/icons";

<Breadcrumb dir="rtl" aria-label="مسار التنقل">
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="#home">الرئيسية</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>
      <ChevronLeftIcon size="sm" />
    </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbLink href="#projects">المشاريع</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator>
      <ChevronLeftIcon size="sm" />
    </BreadcrumbSeparator>
    <BreadcrumbItem>
      <BreadcrumbCurrent>الإعدادات</BreadcrumbCurrent>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Props

Breadcrumb props

PropTypeDefaultDescription
sizesm | md | lgmdSet the path density.
variantplain | underlineplainSet the ancestor-link treatment.
aria-labelstringBreadcrumbName the navigation landmark.
aria-labelledbystringnoneName the navigation landmark from another element.
asWhiskHtmlTagnavChange the Breadcrumb host when its native semantics still fit.
asChildbooleanfalseMerge Breadcrumb presentation into exactly one host element.
classNamestringnoneAdd a class to the Breadcrumb host.

BreadcrumbList props

PropTypeDefaultDescription
asWhiskHtmlTagolChange the BreadcrumbList host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbList presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbList host.

BreadcrumbItem props

PropTypeDefaultDescription
asWhiskHtmlTagliChange the BreadcrumbItem host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbItem presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbItem host.

BreadcrumbLink props

PropTypeDefaultDescription
hrefstringnoneSet an ancestor destination.
targetstringnoneUse native browsing-context behavior.
externalbooleanfalseAdd noopener and noreferrer to the link relation.
asWhiskHtmlTagaChange the BreadcrumbLink host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbLink presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbLink host.

BreadcrumbCurrent props

PropTypeDefaultDescription
childrenReactNodenoneRender the non-interactive current-page label.
asWhiskHtmlTagspanChange the BreadcrumbCurrent host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbCurrent presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbCurrent host.

BreadcrumbSeparator props

PropTypeDefaultDescription
childrenReactNodeChevronRightIconRender decorative separator content.
asWhiskHtmlTagliChange the BreadcrumbSeparator host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbSeparator presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbSeparator host.

BreadcrumbEllipsis props

PropTypeDefaultDescription
childrenReactNode...Render the visible collapsed-path marker.
asWhiskHtmlTagliChange the BreadcrumbEllipsis host when its native semantics still fit.
asChildbooleanfalseMerge BreadcrumbEllipsis presentation into exactly one host element.
classNamestringnoneAdd a class to the BreadcrumbEllipsis host.

Shared props

PropSupportedNotes
as / asChildYesChoose the rendered element for each part with as, or merge that part's presentation into one child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered element of each part.
refYesForwards to the rendered element of each part.
Native HTML attributesYesNative attributes are forwarded to the rendered element of each part.

Accessibility

Breadcrumb renders a named navigation landmark and an ordered list. Use BreadcrumbLink for reachable ancestors and BreadcrumbCurrent for the current page, which receives aria-current="page" without becoming a disabled link. Separators and static ellipses are decorative and hidden from assistive technology. When an ellipsis opens hidden destinations, give it an accessible label. Keep the path labels meaningful without relying on their visual separators.

Content guidance

Use the names people recognise from the hierarchy. The final current-page label should match the page heading.

DoDon't
Projects / Atlas / SettingsHome > Page > Details; a current label that differs from the H1