CynosureComponents / Structure
Breadcrumbs
Shows the trail from the top of a site or app to the current page. Every item but the last is a link back up the trail; the last one is the page being shown. For moving between sections of an app, use SideNav instead.
When to useLink to "When to use"
- Pages nested two or more levels deep: people can see where they are and go back up in one step.
- Above the page title: one Breadcrumbs per page, before the heading.
- Deep trails in tight space: set
maxItemsso the middle collapses into a menu.
Use something else when:
- it is the main navigation between sections: SideNav
- it switches views of the same page: Tabs
- it shows progress through a sequence: Steps
- it moves through pages of results: Pagination
- it is a single link back: Link
UsageLink to "Usage"
import { Breadcrumbs } from "@arshad-shah/cynosure";
import { home } from "@arshad-shah/cynosure/icons";
<Breadcrumbs
items={[
{ label: "Home", href: "/", icon: home },
{ label: "Projects", href: "/projects" },
{ label: "Cynosure" },
]}
/>
<Breadcrumbs items={trail} maxItems={3} />
<Breadcrumbs items={[{ label: "Library", href: "/library", onClick: (event) => { event.preventDefault(); router.push("/library"); } }, { label: "Report" }]} />Items are data, not children. The last item is always the current page, so its href and onClick are ignored. An earlier item is a link with href, a button with only onClick, and plain text with neither.
Collapsing a long trailLink to "Collapsing a long trail"
With more items than maxItems, the first item and the last maxItems - 1 stay. The ones between go into a menu behind a "more" button, listed in trail order. Values under 2 count as 2.
Icons and separatorLink to "Icons and separator"
icon on an item is decorative and sits before the label. separator replaces the chevron between crumbs.
Long names and narrow containersLink to "Long names and narrow containers"
Each name is cut with an ellipsis at a maximum width, and the trail wraps onto more lines instead of overflowing.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
itemsRequired | The trail, from the top of the site to the current page. The last item is the current page. | BreadcrumbItem[] | |
maxItems | Most crumbs to show. With more items, the first one and the last maxItems - 1 stay and the ones between go into a menu behind a "more" button. Values under 2 count as 2. Default: every item is shown. | number | every item is shown |
separator | The icon between crumbs. It is decorative and mirrored in right-to-left text. Default chevronRight. | IconData | `chevronRight` |
size | Text size. Default "md". | "sm" | "md" | "md" |
labels | Replace the built-in English text: nav names the landmark (default "Breadcrumb"), more names the button and the menu of hidden items (default "Show the full path"). | { nav?: string; more?: string; } | |
className | Added to the root element, for layout. | string | |
style | Layout only. Restyle through --cy-breadcrumbs-* tokens. | CSSProperties |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
| Input | Result |
|---|---|
| Tab | Moves through the links and buttons in trail order. The current page is not a tab stop |
| Click, tap, Enter on a crumb | Follows the link, or calls onClick (which can cancel the link with event.preventDefault()) |
| Click, tap, Enter, Arrow Down on the "more" button | Opens the menu of hidden items |
| Arrow Down in the menu | Moves between the hidden items, skipping ones that go nowhere |
| Enter or click on a menu item | The same as choosing that crumb in the trail; the menu closes and focus returns to the button |
| Escape | Closes the menu and returns focus to the button |
- Landmark: a
navnamed "Breadcrumb" (labels.nav) holding an ordered list, as in the WAI-ARIA APG breadcrumb pattern. - Current page: the last item is text with
aria-current="page". - Separators: decorative icons hidden from assistive technology, mirrored in right-to-left layouts.
- Hidden items: an item with neither
hrefnoronClickis listed as disabled in the menu. - Labels:
labels.more(default "Show the full path") names the "more" button and its menu.
TouchLink to "Touch"
The "more" button's hit area grows to 44px on coarse pointers (phones and tablets) without changing its visible size, and the menu's rows are 44px tall.
ThemingLink to "Theming"
Tokens: --cy-breadcrumbs-gap, --cy-breadcrumbs-item-max-width and --cy-breadcrumbs-separator-color.
createTheme({ components: { breadcrumbs: { itemMaxWidth: "16ch", gap: "8px" } } });className and style are for layout only (margin, placement). Change the look through tokens so every product stays consistent.
RelatedLink to "Related"
Link · Menu · SideNav · Tabs · Pagination
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.