Breadcrumb

A trail of links from the top of a hierarchy down to the current page. Use it where pages nest at least two levels deep; on a flat site it only repeats the navigation.

Contract 1.3.0Kit · 2 sets · 12 variantsOpen in Figma

Live preview

Rendered by the component itself from the same generated tokens as the rest of the site.

Length

Max items

<Breadcrumb
  items={[
    { label: 'Home', href: '#' },
    { label: 'Projects', href: '#' },
    { label: 'Graphite', href: '#' },
    { label: 'Settings' },
  ]}
/>

Installation

Install it with the shadcn CLI, along with everything it uses. New project? Set it up first, as Quick start shows.

npx shadcn@latest add https://www.graphite-ui.com/r/breadcrumb.json

import { Breadcrumb } from '@/components/ui/breadcrumb'
import type { Crumb } from '@/components/ui/breadcrumb'

Anatomy

Slots come from the contract, so this list and the code cannot disagree about what the component is made of.

Ordered list of crumb itemsRequiredMinimum 1.
Current-page indicatorRequiredNon-clickable.

Variants

There is no kind or size to pick: the separator is defined once for every trail. What changes is length, and past maxItems (4 by default) the middle collapses behind the kit’s overflow button rather than wrapping onto a second line. Pressing it opens a menu of the hidden crumbs. The kit’s optional leading icon is the icon prop.

Three crumbs

With the kit’s leading icon

Six crumbs, collapsed at maxItems 4

States

Hover and Focus are forced here with the declarations their pseudo-classes carry: primary’s hover step, and the kit’s 1px focus ring outside the label.

Enabled

Hover

Focus

Current only

API reference

Generated from the contract, versioned with it, and checked by drift-check. This table cannot describe props the component does not have.

Breadcrumb props
Prop	Type	Default	Notes
separator style	—	—	Fixed, defined once — not per-instance.
maxItems	number	4	The defined max length. A longer trail keeps its first crumb and its tail and collapses the middle behind one overflow button.
icon	ReactNode	—	The kit's Show Icon slot, a 16px glyph before the first crumb (the kit draws fi-rs-bread-slice). Optional and decorative.

Design tokens

Every swatch is live. Change the source color in the header and this table repaints, because it reads the same roles the component does.

on-surfaceThe current page crumb, the separators and the leading icon (Text/text-primary and Icon/icon-primary in the kit), and a link's colour while pressed.
spacingGaps between crumbs and separators.
primaryLink crumbs and the overflow glyph (Link/link-primary), their hover through primary-hover, and the 1px focus ring through the page-level focus variable.
textEvery crumb and separator in Body/3.

Usage

The contract's prohibitions, written as the choices you will actually face.

Do

Mirror where the page lives in the hierarchy, not the path the reader took to get there.
Use each page’s own title for its crumb, shortened if you must, so the trail and the headings agree.
Set maxItems for the narrowest layout the trail appears in, since it never wraps.
Keep the trail near the top of the page, above the title it ends on.

Don’t

Link the last crumb. Any href on it is ignored, because it stands for “here”, not somewhere to go.
Let a long trail wrap onto a second line. Collapse the middle with maxItems instead.
Style a separator per instance. It is defined once so that every trail in the product reads the same.
Set maxItems so low that the reader has to open the overflow menu to find the parent they need. It reaches the hidden crumbs, but it is an extra step.

Accessibility

What the component does for you, and what it leaves to you.

Landmark: A nav landmark labelled “Breadcrumb”, with the crumbs in an ordered list, so a screen reader announces how many there are and where each sits.
Current page: The last crumb carries aria-current="page" and is plain text, not a link, so it is announced as the current page and is not in the tab order.
Separators: The slashes are aria-hidden. A screen reader hears the list, not the punctuation.
Collapse: The overflow is a menu button named for what it hides, such as “Show 3 more breadcrumbs”. Enter, Space or the arrow keys open a menu of the hidden crumbs; selecting one goes there, and Escape closes it and returns focus to the button.
Focus: Links and the overflow button draw the kit’s 1px --graphite-focus ring outside the label on keyboard focus.

Figma parity

The kit’s Breadcrumb set has a single variant and no variant axes: it is a leading icon and a row of item instances. The item’s own states live in a private build block, so this table maps the set’s structure instead.

Kit axes and how they map to code
Kit axis	Values	Code	How it maps
Items	4 shown · 8 in the set	items	The kit hides the extra instances; the code takes any number and collapses past maxItems.
Icon	Show Icon	icon	The kit’s optional leading glyph, 16px and on-surface, 8px before the first crumb. The kit draws fi-rs-bread-slice; any icon can be passed.
Overflow	An item that opens a menu	maxItems	One to one: the kit’s 12px menu-dots button, on the baseline, opening a Menu of the hidden crumbs.
Underline	Every link state, and Current	—	Links are underlined at rest, as the item set draws them. The kit also underlines the current page, which would make “here” look clickable, so the code leaves it plain and records the slip.
Current	Last item	the last of items	Not a prop. The last crumb is always current, so the choice cannot be made wrong.