Breadcrumb
A breadcrumb shows where the current page sits in a deep hierarchy, as a trail of links back up to the top.
<tk-breadcrumb> <tk-breadcrumb-item href="/">Home</tk-breadcrumb-item> <tk-breadcrumb-item href="/docs">Docs</tk-breadcrumb-item> <tk-breadcrumb-item href="/docs/components">Components</tk-breadcrumb-item> <tk-breadcrumb-item>Breadcrumb</tk-breadcrumb-item> </tk-breadcrumb>
Anatomy
| Part | What it is |
|---|---|
tk-breadcrumb |
a navigation landmark holding an ordered list |
tk-breadcrumb-item with href |
an ancestor page: a muted link |
last tk-breadcrumb-item without href |
the current page: plain, darker text, not a link |
| separator | a chevron between crumbs; decorative |
| overflow button | when collapsed, a "…" button opening a menu of the hidden crumbs |
Crumbs
- An item with
hrefis a link. It is aLink with the quiet look: muted at rest, darker and underlined on hover and focus.targetandrelpass through to it. - The last item without
hrefis the current page. It isn't focusable and screen readers hear it as the current page. - To end the trail at the parent, leave the current page out. Every crumb is then a link.
- To use your router's links, leave out
hrefand put your own<a>in the item.
Separator
Put a glyph in the separator slot to replace the chevron in every gap. It stays
decorative.
<tk-breadcrumb> <span slot="separator">/</span> <tk-breadcrumb-item href="/">Home</tk-breadcrumb-item> <tk-breadcrumb-item href="/blog">Blog</tk-breadcrumb-item> <tk-breadcrumb-item>Release notes</tk-breadcrumb-item> </tk-breadcrumb>
Collapse a long trail
max-items keeps a long trail short. When there are more crumbs than that, only the first
and last stay, and a "…" button between them opens a menu of the rest. Choosing one goes
to that page.
<tk-breadcrumb max-items="4"> <tk-breadcrumb-item href="/">Home</tk-breadcrumb-item> <tk-breadcrumb-item href="/store">Store</tk-breadcrumb-item> <tk-breadcrumb-item href="/store/pets">Pet supplies</tk-breadcrumb-item> <tk-breadcrumb-item href="/store/pets/cats">Cats</tk-breadcrumb-item> <tk-breadcrumb-item href="/store/pets/cats/food">Food</tk-breadcrumb-item> <tk-breadcrumb-item>Wet food</tk-breadcrumb-item> </tk-breadcrumb>
- The button's name says how many crumbs it hides: "Show 4 more breadcrumbs".
- Crumbs in the menu don't open in a new tab or show a link's context menu. The first and last crumbs stay real links.
- Without
max-items, a trail too long for its container wraps onto a second line.
Icons
Put a tk-iconlabel; that
becomes the link's name.
<tk-breadcrumb> <tk-breadcrumb-item href="/account"><tk-icon name="user" label="Account"></tk-icon></tk-breadcrumb-item> <tk-breadcrumb-item>Security</tk-breadcrumb-item> </tk-breadcrumb>
When to use
- Use a breadcrumb in a hierarchy three or more levels deep, such as docs, product categories, settings, or file paths.
- Use a stepper for a linear flow such as a checkout. A breadcrumb shows place, not progress.
- Use a single back
link for a shallow site or to go back one level. - Use a
Navigation menu orSidebar for main navigation. A breadcrumb sits next to it, never in its place.
Content
- Use each page's own title as its crumb, so the label names the destination.
- Keep crumbs short, in sentence case, with no end punctuation.
- Don't add words like "Back to" or "Go to".
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use a breadcrumb in a deep hierarchy | Use it for checkout steps or a flat site |
Leave href off the current page |
Make the current page a link |
| Use each page's title as its crumb | Write "Back" or "Click here" |
Collapse a long trail with max-items |
Let a trail run onto three lines |
Give an icon-only crumb a label |
Leave an icon-only crumb unnamed |
Related
Link : each crumb is a quiet link.Menu : holds the collapsed crumbs.Navigation menu andSidebar : main navigation.Page header : where a breadcrumb usually sits, above the title.
API
tk-breadcrumb
| Attribute | Type | Default | What it does |
|---|---|---|---|
label |
string | Breadcrumb |
the landmark's accessible name |
max-items |
number | — | with more crumbs than this, keep the first and last and put the rest in a "…" menu |
| Slot | Content |
|---|---|
| default | tk-breadcrumb-item elements, top level first, current page last |
separator |
a glyph that replaces the chevron for the whole trail |
tk-breadcrumb-item
| Attribute | Type | Default | What it does |
|---|---|---|---|
href |
string | — | the destination; leave it off the last item to mark the current page |
target |
string | — | the link's target; _blank adds noopener noreferrer |
rel |
string | — | extra rel values for the link |
| Slot | Content |
|---|---|
| default | the crumb text, the accessible name; an optional leading tk-icon |
Events
No custom events. Crumb links navigate like any link.
CSS
tk-breadcrumb::part(list): the<ol>.tk-breadcrumb-item::part(link): the crumb'sLink , whenhrefis set.
Tokens
| Part | Tokens |
|---|---|
| crumb link | text/secondary; hover and focus text/default + underline |
| current page | text/default |
| separator | icon/tertiary, 1em, space-8 on each side |
| focus ring | border/accent/focus |
| overflow button and menu | from |
Text size comes from the surrounding element. Values per theme:
Accessibility
Built in:
- A
<nav>landmark named "Breadcrumb" around an ordered list. - The current page has
aria-current="page"and isn't focusable. - Separators are hidden from screen readers.
- Every crumb link is a real link with a visible focus ring.
- The overflow button is named and works with the
Menu keyboard.
Your part:
- Put the breadcrumb before
<main>, so a skip link can pass it. - With two breadcrumbs, or a breadcrumb and another
<nav>, give each a differentlabel. - Name the destination in each crumb, and give an icon-only crumb a
label. - On a dark or inverse surface, keep crumb text at 4.5:1 or more.
| Key | Action |
|---|---|
Tab |
moves through the crumb links and the "…" button; skips the current page |
Enter |
follows the focused link |
Enter / Space / Down on "…" |
opens the menu; then the |