Skip to main content

Breadcrumbs

Shows where the user is and links back up the hierarchy.

import { Breadcrumbs } from "@/fragments/ui";Source

Preview

<Breadcrumbs>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>
</Breadcrumbs>

Installation

npx @usefragments/cli add breadcrumbs

Writes src/fragments/ui/components/Breadcrumbs plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Breadcrumbs is a compound: import the root and reach its parts through dot notation.

  • Breadcrumbs.Item
  • Breadcrumbs.Separator

Each ancestor links; the last one does not.

<Breadcrumbs>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>
</Breadcrumbs>

Examples

With Icons

Glyphs mark what kind of thing each level is.

<Breadcrumbs>
  <Breadcrumbs.Item
    href="#"
    icon={
      <svg viewBox="0 0 16 16" fill="currentColor">
        <path d="M8 1.25l-7 6v7.5c0 .138.112.25.25.25H5.5V10h5v5h4.25a.25.25 0 0 0 .25-.25v-7.5l-7-6z" />

Collapsed

Middle levels fold behind an ellipsis.

<Breadcrumbs maxItems={3}>
  <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Section</Breadcrumbs.Item>
  <Breadcrumbs.Item current>Current Page</Breadcrumbs.Item>

Custom Separator

Any node can replace the slash.

<Breadcrumbs
  separator={
    <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor">
      <path
        fillRule="evenodd"
        d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06z"

Custom Landmark Label

Renames the landmark screen readers announce.

<Breadcrumbs label="Documentation breadcrumbs">
  <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
  <Breadcrumbs.Item href="#">Components</Breadcrumbs.Item>
  <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
</Breadcrumbs>

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setBreadcrumb items (use Breadcrumbs.Item)
separatornode/Custom separator between items
maxItemsnumberNot setMaximum visible items before collapsing middle items with ellipsis
labelstringBreadcrumbCustom aria-label for the breadcrumb nav landmark

Accessibility

  • Uses <nav aria-label="Breadcrumb"> for landmark navigation
  • Current page is marked with aria-current="page"
  • Separators are hidden from screen readers with aria-hidden
  • Ellipsis button has aria-label for collapsed items

Standards

Guidance

Use when

  • Nested content more than two levels deep
  • Jumping back to a parent in one click
  • Documentation and catalogue hierarchies

Avoid when

  • Flat structures with no parents (use Tabs or header navigation)
  • Steps in an order (use Stepper)
  • Primary navigation (use Sidebar or Header)

Related

  • TabsalternativeUse Tabs for flat, non-hierarchical navigation
  • SidebarcomplementaryBreadcrumbs complement sidebar navigation for deep hierarchies

Next steps