Breadcrumb | Glaze design system

Fit

When to use it

Use: The page is three or more levels deep: workspace, agent, run.
Use: A detail page needs a way back to its list and to the levels above it.
Not for: The page is a peer of its neighbours, such as Runs beside Settings. Use Tabs.
Not for: The person moves through a flow in order. Use Steps.
Not for: The page is one level below home: the page title is enough.

7 rules

Should: Use BreadcrumbTrail with items; compose the parts by hand only for a fixed trail of three or fewer. Because the trail measures its container and folds crumbs into a menu in a fixed order, which hand-built parts never do.
Must: Make the last item the current page, with no href. Because the current page is text-1 and not a link, and aria-current="page" tells a screen reader where it is.
Must: Order items from the root to the current page. Because the trail folds from the left and keeps the current page last, so a reversed list folds the wrong crumbs.
Must: Mark an ID crumb with id: true, or wrap it in BreadcrumbId. Because it sets the ID in mono at 0.8 and cuts the middle while keeping the type prefix, so run_8f2a…e5b6a7 stays readable and the line keeps its height.
Must: Pass renderLink with the router's link, or render on BreadcrumbLink. Because without it every crumb is a plain anchor and each press reloads the page.
Never: Render two breadcrumbs on one page. Because each is a nav landmark named Breadcrumb, so a screen reader cannot tell them apart.
Should: Use each page's title as its crumb label, and a short plural noun for a list level. Because a crumb that names a page differently from its heading sends the person somewhere they do not recognise.

5 checks

: The root is a nav named Breadcrumb holding an ordered list; the chevrons are aria-hidden.
: The current page has aria-current="page" and is not a link.
: The fold button names its count ("2 more levels") and opens a menu of real links with arrow keys and Escape.
: A cut current page carries its full text as a title; a cut ID keeps the whole ID for screen readers.
: Links are text-2 at 5.5:1 and underline under the pointer, so a link is never told by colour alone; focus is the 2px ink ring.

2 keys

Tab: Moves through the links and the fold button; the current page is not a stop.
Enter, Space: Follows a link, or opens the fold menu.

8 edge cases

Trail too wide: Middle crumbs fold into the menu from the left, then the current page truncates, then the root joins the menu.
Current page: Never shrinks below 80px, and the trail never ends in a chevron.
One item: Renders the current page alone and truncates it if it does not fit.
Long ID: Past 18 characters it shows the type prefix and 4 characters, an ellipsis and the last 6.
First paint: It measures a hidden copy before it decides, so nothing jumps while it folds.
Container resizes: It measures again and unfolds as room returns.
Right to left: The trail mirrors and the chevrons turn; labels take dir="auto".
Zoom 200%: Crumbs fold sooner, and every folded one stays one menu press away.

5 props

items: Crumb[] default required
renderLink: (href: string) => ReactElement
Crumb id: boolean default false
Breadcrumb parts: BreadcrumbList, Item, Link, Page, Separator, Ellipsis, Id
className: string

13 tokens