Skip to main content

Breadcrumbs

Accessible navigation trail. Icons, separators, collapse, SPA routing.

Quick start 
import { Breadcrumbs } from "mates-ui";

Breadcrumbs({ items: [{ label: "Home", href: "/" }, { label: "Here" }] });

Basic

import { html, renderApp } from 'mates';
import { Breadcrumbs } from 'mates-ui';

const App = () => () => html`
${Breadcrumbs({
items: [
{ label: "Home", href: "#" },
{ label: "Settings", href: "#" },
{ label: "Profile" },
],
})}
`;

renderApp(App, document.getElementById('app'));

With icons

import { html, renderApp } from 'mates';
import { Breadcrumbs } from 'mates-ui';
import { HomeIcon, FolderIcon, CodeIcon } from 'mates-icons';

const App = () => () => html`
${Breadcrumbs({
items: [
{ label: "Home", href: "#", icon: HomeIcon() },
{ label: "Projects", href: "#", icon: FolderIcon() },
{ label: "mates-ui", href: "#", icon: CodeIcon() },
{ label: "Components" },
],
})}
`;

renderApp(App, document.getElementById('app'));

Custom separator

import { html, renderApp } from 'mates';
import { Breadcrumbs } from 'mates-ui';
import { ChevronRightIcon } from 'mates-icons';

const App = () => () => html`
${Breadcrumbs({
items: [
{ label: "Dashboard", href: "#" },
{ label: "Users", href: "#" },
{ label: "Alice Johnson" },
],
separator: html`${ChevronRightIcon({ size: 14 })}`,
})}
`;

renderApp(App, document.getElementById('app'));

Collapsed with expand

import { html, atom, renderApp } from 'mates';
import { Breadcrumbs } from 'mates-ui';

const ITEMS = [
{ label: "Home", href: "#" },
{ label: "Workspace", href: "#" },
{ label: "Projects", href: "#" },
{ label: "mates", href: "#" },
{ label: "Packages", href: "#" },
{ label: "mates-ui" },
];

const App = () => {
const expanded = atom(false);
return () => html`
${expanded()
? Breadcrumbs({ items: ITEMS })
: Breadcrumbs({
items: ITEMS,
maxItems: 4,
trailingVisible: 2,
onExpand: () => expanded.set(true),
})}
`;
};

renderApp(App, document.getElementById('app'));

Sizes

import { html, renderApp } from 'mates';
import { Breadcrumbs } from 'mates-ui';

const ITEMS = [
{ label: "Home", href: "#" },
{ label: "Docs", href: "#" },
{ label: "API Reference" },
];

const App = () => () => html`
<x-col gap="var(--md-space-3)">
${Breadcrumbs({ items: ITEMS, size: "sm" })}
${Breadcrumbs({ items: ITEMS, size: "md" })}
${Breadcrumbs({ items: ITEMS, size: "lg" })}
</x-col>
`;

renderApp(App, document.getElementById('app'));

Breadcrumbs

import { Breadcrumbs } from "mates-ui";
Prop Type Default Description
attr AttrMap — Extra HTML attributes forwarded to the root element.
breadcrumbLabel string "Breadcrumb" Aria-label for the nav element.
classes string | string[] — Extra root classes — joined and appended after built-in classes.
data DataAttrMap — Root `data-*` map (`testId` → `data-testid`). `testId` prop / `attr` win over `data`.
id string — Root `id` shorthand (`attr.id` wins). Form native-control `id` props are unchanged.
items* BreadcrumbItem[] — Ordered list of breadcrumb items to render.
maxItems number — Maximum number of items shown before collapsing the middle to an ellipsis button.
on OnEventMap — DOM event handlers on the root element.
onExpand () => void — Callback invoked when the user clicks the "…" ellipsis button to expand a collapsed trail.
separator TemplateResult — Custom separator node rendered between items. Defaults to "/".
showFullPathLabel string "Show full path" Aria-label and title of the ellipsis expand button.
size "sm" | "md" | "lg" "md" Overall text and icon size of the breadcrumb trail.
style StyleMap — Inline CSS on the root element.
style StyleMap — Root inline CSS (`style` prop; `style` wins if both set).
testId string — Overrides default data-testid for testing.
trailingVisible number 1 Number of items always shown at the end of the trail when the list is collapsed.

BreadcrumbItem

Prop Type Default Description
href string — When provided the item renders as an <a> anchor.
icon IconInput — Optional Material Symbol icon shown before the label.
label* string — Visible text of the breadcrumb item.
onClick (e: MouseEvent) => void — Click handler. Takes precedence over href when both are set.

CSS tokens

Token Role
--md-color-primary Colour of the last (current) item.
--md-color-text Colour of the separator glyphs.
--md-color-text-muted Colour of inactive (non-last) items.

Caveats

  • `onExpand` is required when `maxItems` is set — without it the ellipsis button does nothing.
  • When both `href` and `onClick` are set, `onClick` is used and `href` is ignored.
  • The last item is always rendered without a link regardless of `href`.