ShineUI / Components / Menus and navigation

Breadcrumb

You are here.

<sui-breadcrumb>Menus and navigationStable

About

Path trail with chevron separators for drill-in screens, marked up as a nav over an ordered list. The last crumb is the current page: bold, not clickable, and marked aria-current="page". Earlier crumbs are buttons, or real links when they carry href. A long trail collapses its middle behind an ellipsis with maxItems.

Usage

<sui-breadcrumb aria-label="Breadcrumb, Basic"></sui-breadcrumb> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); const el = document.querySelector("sui-breadcrumb"); el.items = [{ label: "Sales", icon: "fa-regular fa-folder" }, { label: "Invoices" }, { label: "INV-1043" }]; /* SuiBreadcrumbItem[] */ el.addEventListener("suiNavigate", (e) => console.log(e.detail)); </script>

import { SuiBreadcrumb } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { const items = [{ label: "Sales", icon: "fa-regular fa-folder" }, { label: "Invoices" }, { label: "INV-1043" }]; /* SuiBreadcrumbItem[] */ return <SuiBreadcrumb aria-label="Breadcrumb, Basic" items={items} onSuiNavigate={(e) => console.log(e.detail)} />; }

import { Component } from "@angular/core"; import { SuiBreadcrumb } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiBreadcrumb], template: `<sui-breadcrumb aria-label="Breadcrumb, Basic" [items]="items" (suiNavigate)="onChange($event)"></sui-breadcrumb>`, }) export class Example { items = [{ label: "Sales", icon: "fa-regular fa-folder" }, { label: "Invoices" }, { label: "INV-1043" }]; // SuiBreadcrumbItem[] onChange(e: CustomEvent) { console.log(e.detail); } }

Basic

The trail is a nav named Breadcrumb; the chevrons are decorative and hidden from screen readers, and every earlier crumb is a button in document order. The last crumb is plain text with aria-current="page" that takes no focus.

<sui-breadcrumb aria-label="Breadcrumb, Basic"></sui-breadcrumb>

// setup(root): properties and events setup(root) { root.querySelector('sui-breadcrumb').items = invoiceTrail(); }

Real links

A crumb with href renders an anchor, so middle-click and copy-link work and the browser navigates on its own. suiNavigate still fires alongside.

<sui-breadcrumb aria-label="Breadcrumb, Real links" id="bc-links"></sui-breadcrumb>

// setup(root): properties and events setup(root) { root.querySelector('#bc-links').items = [ { label: 'Home', icon: 'fa-solid fa-house', href: '#/' }, { label: 'Accounting', href: '#/accounting' }, { label: 'Chart of accounts', href: '#/accounting/accounts' }, { label: 'Operating 4402' }, ]; }

Ellipsis

max-items collapses a long trail to its first crumb, an ellipsis and the last few, and a new items array collapses it again. The ellipsis is a button named by how many crumbs it hides; pressing it reveals the whole trail and moves focus to the first revealed crumb.

<sui-breadcrumb aria-label="Breadcrumb, Ellipsis" id="bc-ellipsis" max-items="3"></sui-breadcrumb>

// setup(root): properties and events setup(root) { root.querySelector('#bc-ellipsis').items = [ { label: 'Home', icon: 'fa-solid fa-house', href: '#/' }, { label: 'Accounting', href: '#/accounting' }, { label: 'Chart of accounts', href: '#/accounting/accounts' }, { label: 'Assets', href: '#/accounting/accounts/assets' }, { label: 'Bank', href: '#/accounting/accounts/assets/bank' }, { label: 'Operating 4402' }, ]; }

Events

Clicking any crumb but the last emits suiNavigate with its destination, a string: the href, else the key, else the label, so a router can take over. The current page emits nothing because it is not a control.

Nothing clicked yet.

<div style="display:flex;flex-direction:column;gap:10px;align-items:flex-start"> <sui-breadcrumb aria-label="Breadcrumb, Navigate event" id="bc-events"></sui-breadcrumb> <span id="bc-log" style="font:460 13px/1.6 var(--font-sans);color:var(--ink-muted)">Nothing clicked yet.</span> </div>

// setup(root): properties and events setup(root) { const log = root.querySelector('#bc-log'); const el = root.querySelector('#bc-events'); el.items = [{ label: 'Sales', key: 'sales', icon: 'fa-regular fa-folder' }, { label: 'Invoices' }, { label: 'INV-1043' }]; el.addEventListener('suiNavigate', (e) => { log.textContent = `suiNavigate: ${e.detail}.`; }); }

Keyboard

Key	Action
`Tab`	Moves through the crumbs in document order. The current page is plain text and takes no focus.
`Enter`	Follows a link crumb, or emits suiNavigate from a button crumb. On the ellipsis, reveals the hidden crumbs and moves focus to the first of them.
`Space`	Activates a button crumb or the ellipsis. A link crumb follows on Enter alone, as any link does.

API

`<sui-breadcrumb>`

Property	Attribute	Type	Default	Description
`items`	property only	`SuiBreadcrumbItem[]`	`[]`	Crumbs: `{ label, key?, icon?, href?, target? }[]`; the last one is the current page. Property, not attribute.
`maxItems`	`max-items`	`number`	`0`	Most crumbs to show before the middle of the trail collapses behind an ellipsis: the first crumb stays, then the ellipsis, then the last `maxItems - 1`. Pressing the ellipsis reveals the whole trail and moves focus to the first revealed crumb. `0` (the default) never collapses; values below 2 are treated as 0. A new `items` array collapses again.

Event	Detail	React	Vue	Description
`suiNavigate`	`string`	`onSuiNavigate`	`@sui-navigate`	Fires when a non-last crumb is clicked; detail is the destination, a string as on every navigation element: the crumb's `href`, or for a crumb without one its `key`, else its label. A link still follows its `href`.

Method	Signature	Description
`setFocus()`	`setFocus() => Promise<void>`	Moves keyboard focus to the first crumb, the start of the trail.

`SuiBreadcrumbItem` interface
`label`	`string`
`key?`	`string`	Identity for a router: `suiNavigate` reports it for a crumb without `href`, so a handler keys off something that does not move when the labels are translated or edited.
`icon?`	`string`	Font Awesome class, e.g. "fa-regular fa-folder".
`href?`	`string`	Renders the crumb as a real link. Without it the crumb is a button that only emits `suiNavigate`.
`target?`	`string`	Link target for a crumb with `href`, e.g. `_blank`. A `_blank` crumb gets `rel="noopener"`.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.