Components · Navigation
Breadcrumb
BetaShows where a page sits, such as Programs › Strength block.
- Source
components/ui/breadcrumb.tsx - shadcn/ui Breadcrumb
- Figma: not linked yet (Q13)
When to use
- On pages two or more levels deep, so the coach can see where they are and step back up: Programs › Strength block › Week 3.
- When people arrive from search, a notification or a shared link and need the path back to the parent: a client's check-in, opened from an email.
When not to use
- On top-level pages that are already in the Sidebar: Dashboard, Clients. The sidebar shows where they are.
- To show steps in a task (onboarding, a program wizard): use a stepper. A breadcrumb is a place, not a progress bar.
- To switch between sibling views of one thing: use Tabs.
- As the only navigation on a page: it complements the sidebar, it doesn't replace it.
Anatomy
- 1. Breadcrumb: a nav landmark around an ordered list
- 2. Link: an ancestor page, in muted text
- 3. Separator: a chevron, hidden from screen readers; mirrors in RTL
- 4. Current page: full-strength text, not a link, aria-current="page"
Variants
| Variant | Use for |
|---|---|
| Full path | Up to 4 levels. Show every level. |
| Collapsed | 5 levels or more, or narrow screens. Keep the first level and the last two; the middle collapses into a "More" button that opens a dropdown menu of the hidden levels. |
The separator is a chevron by default. Pass a child to BreadcrumbSeparator to change it, but keep one style across the product.
States
| State | What changes | Token |
|---|---|---|
| Link, rest | Muted text | text-muted-foreground |
| Link, hover | Text darkens | hover:text-foreground |
| Link, focus-visible | The browser's default focus outline. The component sets no focus style of its own; see the note below | — |
| Current page | Full-strength text, regular weight | text-foreground, font-regular |
| Collapsed levels | A 36px "More" button; its menu uses the dropdown menu tokens | size-9 |
BreadcrumbLink shows the standard focus ring (ring-ring/50); upstream shadcn had none and fell back to the browser outline.
Usage guidelines
- Start at the top-level section, not at "Home": the sidebar already gives the way home.
- The last item is the current page, and it matches the page title. It is never a link.
- Put the breadcrumb above the page title, at the start edge.
- Each level is a page the coach can actually open. Don't add levels that only exist as groupings.
Content guidelines
- Use each page's own title, shortened if needed: "Strength block", not "Program: Strength block (12 weeks)".
- Sentence case, no punctuation. Client names in full: "Sara Al-Harbi".
- Keep labels under about 24 characters. Long names truncate in the page title, not in the breadcrumb.
- Arabic uses the same page titles as the Arabic navigation: "البرامج › برنامج القوة › الأسبوع 3". Numbers stay in Western digits.
Accessibility
| Key | Does |
|---|---|
| Tab | Moves through the links. The current page is not a link, so it is skipped |
| Enter | Opens the focused link |
| Enter / Space on "More" | Opens the menu of hidden levels; arrow keys move through it, Escape closes it and returns focus to the button |
- A
navlandmark labelled "Breadcrumb" (fromlib/ui-labels, "مسار التنقل" in Arabic), around an ordered list. Screen readers list it with the other landmarks. - Separators are
aria-hidden, so the list reads as "Programs, link. Strength block, link. Week 3, current page", without "chevron". - The current page has
aria-current="page"and is plain text, announced as "Week 3, current page". Upstream shadcn also gave itrole="link"andaria-disabled="true"("link, dimmed"); this version drops them. - The collapsed "More" button needs an
aria-labelthat says what it hides: "Show 2 hidden levels".BreadcrumbEllipsishides only its icon; its visually hidden "More" text (from the UI labels, Arabic in Arabic screens) is read, but a specific label on the button is clearer. - Muted links on the background pass AA in both themes; see the contrast matrix.
RTL
The path reads from right to left: "Programs" is on the right. The chevron separators mirror (rtl:-scale-x-100), so they point from parent to child in both directions. The "More" icon (three dots) does not mirror. The dropdown menu opens aligned to the start edge.
Tokens used
Read from components/ui/breadcrumb.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.
| Token | Utilities | SuperCoach | Coach |
|---|---|---|---|
| --foreground | text-foreground | neutral-950 | neutral-950 |
| --muted-foreground | text-muted-foreground | neutral-600 | neutral-600 |
| --ring | ring-ring/50 | brand-600 | orange-500 |
- Radius
rounded-sm - Type
font-regular - Type
text-sm
Props
<Breadcrumb>
Also takes every prop of <nav>
No props of its own.
<BreadcrumbList>
Also takes every prop of <ol>
No props of its own.
<BreadcrumbItem>
Also takes every prop of <li>
No props of its own.
<BreadcrumbLink>
Also takes every prop of <a>
| Prop | Type | Default |
|---|---|---|
| asChild? | boolean | — |
<BreadcrumbPage>
Also takes every prop of <span>
No props of its own.
<BreadcrumbSeparator>
Also takes every prop of <li>
No props of its own.
<BreadcrumbEllipsis>
Also takes every prop of <span>
No props of its own.
Replaces in coach-admin
From the read-only audit of coach-admin: 4 style values, 4 uses.
coach-admin's breadcrumb is CoreUI's .breadcrumb in the page header, mostly unstyled by the app. src/views/Base/Breadcrumbs is a CoreUI demo page (DECISIONS #10).
Classes and selectors
.breadcrumb2.breadcrumb-item a1
Files
scss/core/_breadcrumb.scss1
The inventory lists the first 12 locations of each value, so file counts are a lower bound.
SCSS variables in these styles
$layout-transition-speednot a color: spacing, size or layout$zindex-stickynot a color: spacing, size or layout$breadcrumb-bordersnot a color: spacing, size or layout