Skip to content
flyingsalmon

Breadcrumb

A single-line trail of the current page's ancestors, each a link back up, ending in the current page as plain text.

Installation

npx shadcn@latest add @flyingsalmon/breadcrumb

Usage

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'

export function BreadcrumbUsage() {
  return (
    <Breadcrumb>
      <BreadcrumbItem link href="/trips">
        Trips
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem active>Kyoto in autumn</BreadcrumbItem>
    </Breadcrumb>
  )
}

Examples

Collapsed trail

From four levels, keep the root, the parent, and the current page, and put everything between the root and the parent behind the ellipsis. Open the menu: the hidden levels run from the highest ancestor down.

A long page title

The current page truncates. Pass the full text as title so it stays readable on hover. The links never truncate, so every ancestor reads in full.

Guidelines

When to use

  • To show where a page sits in a hierarchy and let the traveller climb back up: Trips, then Kyoto in autumn, then Day 3.
  • Above the title of any page at least two levels deep.

When not to use

  • Use Sidebar to move between the sections of the app. A breadcrumb moves up within one section; the sidebar holds all of them.
  • Use Stepper for a position in a sequence someone is walking through, because a hierarchy has no "next".
  • Use Pagination to move between the numbered pages of a list, because a breadcrumb never lists siblings.

Do and don’t

  • Do
    Put the trail above the page title, in muted small text.The title stays the loudest thing on the page and the trail reads as its address, quiet until the traveller wants to climb.
  • Don’t
    Show a trail on a top-level page.A trail of one says nothing the page title has not already said.
  • Don’t
    Change the trail with the route the traveller took to the page.The trail shows where the page lives. Arriving from search or a shared link shows the same trail, so each level always leads to the same parent.
  • Do
    Keep the trail on one line. From four levels, show the root, an ellipsis, the parent, and the current page.A wrapped trail stops reading as one path. The hidden levels stay one press away in the ellipsis menu.
  • Do
    Let the current page truncate and keep every ancestor whole.The traveller already knows the page they are on from its title; the ancestors are where they might go, so those stay readable.
  • Don’t
    Make the current page a link.There is nowhere to go from it. The trail ends in plain text where the traveller already is.

Accessibility

KeyDescription
TabMoves through the ancestor links and the ellipsis trigger. The current page takes no focus.
EnterSpaceArrowDownOn the ellipsis trigger, opens the menu of hidden levels.
ArrowDownArrowUpMoves through the hidden levels in the open menu.
EscapeCloses the menu and returns focus to the ellipsis trigger.

The root is a nav named “Breadcrumb” that holds an ordered list; aria-label overrides the name. Separators are presentational and hidden, so a screen reader hears the levels and nothing between them. The current page carries aria-current="page" and no link role, so nothing in the trail announces as a link that goes nowhere. The ellipsis trigger is named “Show hidden levels”, and its aria-label overrides that.

API

Breadcrumb

Renders the nav and the ol inside it. Other props go to the ol.

PropTypeDefaultDescription
aria-labelstring"Breadcrumb"The name of the nav landmark.

BreadcrumbItem

One item, three shapes. link and active are mutually exclusive and the types enforce it. With neither, the item is a bare list item.

PropTypeDefaultDescription
linktrue–Makes the item an ancestor and renders an anchor. Takes every anchor attribute, such as href.
asChildbooleanfalseWith link, renders your router link with the breadcrumb styling on it.
activetrue–Makes the item the current page: plain text with aria-current="page".

BreadcrumbEllipsis

Owns the dropdown menu, its trigger, and its content. Place it in a BreadcrumbItem with neither link nor active. The trail measures nothing, so you decide which levels move into it.

PropTypeDefaultDescription
childrenReactNodeRequiredThe hidden levels as BreadcrumbEllipsisMenuItem elements, highest ancestor first.
aria-labelstring"Show hidden levels"The name of the trigger button.

BreadcrumbEllipsisMenuItem takes the dropdown menu item props, including asChild for a link. BreadcrumbSeparator takes only list item props and holds a fixed chevron. The trail inserts no separators: place one between each pair of items yourself, so a conditional or collapsed level never leaves a stray chevron.