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/breadcrumbUsage
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
Router links
A link item takes asChild and renders your router's link with the breadcrumb's styling, so the trail navigates without a page reload.
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
- DoPut 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’tShow a trail on a top-level page.A trail of one says nothing the page title has not already said.
- Don’tChange 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.
- DoKeep 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.
- DoLet 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’tMake the current page a link.There is nowhere to go from it. The trail ends in plain text where the traveller already is.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves through the ancestor links and the ellipsis trigger. The current page takes no focus. |
| EnterSpaceArrowDown | On the ellipsis trigger, opens the menu of hidden levels. |
| ArrowDownArrowUp | Moves through the hidden levels in the open menu. |
| Escape | Closes 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | "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.
| Prop | Type | Default | Description |
|---|---|---|---|
| link | true | – | Makes the item an ancestor and renders an anchor. Takes every anchor attribute, such as href. |
| asChild | boolean | false | With link, renders your router link with the breadcrumb styling on it. |
| active | true | – | 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | Required | The hidden levels as BreadcrumbEllipsisMenuItem elements, highest ancestor first. |
| aria-label | string | "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.