Appearance
OrigamBreadcrumb
<OrigamBreadcrumb> renders a navigation trail (<nav> containing an <ol> of crumbs) from an items array, with a divider between consecutive crumbs. It is composed of three components:
<OrigamBreadcrumb>— the<nav>root, iteratesitemsand wires up crumb + divider rendering.<OrigamBreadcrumbItem>— a single crumb (link or plain span).<OrigamBreadcrumbDivider>— the separator between two crumbs (a character or anOrigamIcon).
Basic usage
vue
<template>
<OrigamBreadcrumb :items="items" />
</template>
<script setup lang="ts">
const items = [
{ title: 'Home', href: '/' },
{ title: 'Section', href: '/section' },
{ title: 'Current' },
]
</script>Items also accept plain strings — a string item becomes { title: item } with no link:
vue
<template>
<OrigamBreadcrumb :items="['Home', 'Section', 'Current']" />
</template>The last item in items is always normalized to disabled: true and forced active (aria-current="page") — this reflects "you are here" and matches the standard breadcrumb pattern. active on any OTHER item is ignored: only one item can be the current page, and it's always the last one (#386).
An active config object (IActiveState — bgColor, border, rounded, …) is NOT destroyed on the last item: the item's own item.active config wins if set, otherwise the root <OrigamBreadcrumb active="…"> default is used, otherwise it's a bare true. Either way enabled: true is injected into the resolved config so the visual override renders AND the item stays active — an object config alone doesn't force isActive (see IActiveProps).
vue
<template>
<OrigamBreadcrumb :active="{ bgColor: 'primary' }" :items="items" />
</template>Divider
divider (default '/') is forwarded to every <OrigamBreadcrumbDivider> between two crumbs. It accepts a plain string, or an MDI icon identifier — when the value matches a known MDI_ICONS entry, an <OrigamIcon> is rendered instead of literal text.
vue
<template>
<OrigamBreadcrumb :items="items" :divider="MDI_ICONS.CHEVRON_RIGHT" />
</template>Color, density, shape, spacing
<OrigamBreadcrumb> exposes the standard visual surface — color/bgColor, density, rounded, border (+borderColor/ borderStyle), elevation, padding*/margin*. color, bgColor, density, hover, active and disabled are also forwarded as defaults to every child <OrigamBreadcrumbItem> (items that set their own value still win):
vue
<template>
<OrigamBreadcrumb
:items="items"
color="primary"
density="compact"
rounded="small"
border
/>
</template>Passing both
colorandbgColorwith the same intent is intentional — it's what lets each item's auto-contrast branch insideuseStateEffectpick a legible foreground against the shared background, instead of resolving a subtle "on-bg" tint meant for a transparent surface.
Disabling the whole trail
disabled on <OrigamBreadcrumb> is forwarded as a default to every item — combined with each item's own disabled (the last item is always disabled regardless).
Slots
| Component | Slot | Slot props | Description |
|---|---|---|---|
<OrigamBreadcrumb> | default | — | Overrides the entire <ol> rendering. |
<OrigamBreadcrumb> | item.{index} | { item, index } | Overrides a single crumb by index. |
<OrigamBreadcrumb> | item | { item, index } | Overrides every crumb's rendering (falls back to <origam-breadcrumb-item v-bind="item">). |
<OrigamBreadcrumb> | item.title | — | Passed through as the default slot of the fallback <origam-breadcrumb-item> — lets you customize the title content without replacing the whole item. |
<OrigamBreadcrumb> | divider.{index} | { divider } | Overrides a single divider by index. |
<OrigamBreadcrumb> | divider | { divider } | Overrides every divider (falls back to <origam-breadcrumb-divider :divider="divider">). |
<OrigamBreadcrumbItem> | default | — | Overrides the crumb's content (falls back to <span></span>). |
<OrigamBreadcrumbItem> | prepend | — | Overrides the prepend icon/avatar. |
<OrigamBreadcrumbItem> | append | — | Overrides the append icon/avatar. |
<OrigamBreadcrumbDivider> | default | — | Overrides the divider content (falls back to the icon/character). |
vue
<template>
<OrigamBreadcrumb :items="items">
<template #item="{ item, index }">
<OrigamBreadcrumbItem v-bind="item" :prepend-icon="index === 0 ? MDI_ICONS.HOME : undefined" />
</template>
<template #divider>
<OrigamIcon :icon="MDI_ICONS.CHEVRON_DOUBLE_RIGHT" />
</template>
</OrigamBreadcrumb>
</template>Emits
| Component | Event | Payload | Description |
|---|---|---|---|
<OrigamBreadcrumbItem> | click:prepend | MouseEvent | Clicked the prepend slot. |
<OrigamBreadcrumbItem> | click:append | MouseEvent | Clicked the append slot. |
<OrigamBreadcrumbItem> | update:hover | boolean | v-model companion of the hover prop: true on mouseenter, false on mouseleave. |
<OrigamBreadcrumb> and <OrigamBreadcrumbDivider> emit nothing of their own.
Props
<OrigamBreadcrumb>
ts
interface IBreadcrumbProps extends IColorProps, IBgColorProps, ITagProps,
ICommonsComponentProps, IDensityProps, IRoundedProps, IPaddingProps,
IMarginProps, IBorderProps, IElevationProps, IHoverProps,
IActiveProps {
disabled?: boolean
divider?: string | TIcon
items?: Array<TBreadcrumbItem>
}| Prop | Type | Default | Description |
|---|---|---|---|
items | Array<string | Partial<IBreadcrumbItemProps>> | [] | Crumbs to render. String entries become { title }. |
divider | string | TIcon | '/' | Separator between crumbs — text or MDI icon id. |
tag | string | 'nav' | Root element/component. |
density | TDensity | 'default' | Compresses the root's padding. |
disabled | boolean | — | Forwarded as a default disabled to every item. |
color / bgColor | TColor | — | Forwarded as defaults to every item. |
hover / hoverClass / active / activeClass | boolean | IHoverState / string / boolean | IActiveState / string | — | Forwarded as defaults to every item — only when explicitly passed (usePassedProps), so an unset prop doesn't coerce to false and silently override the item's own value. |
rounded, border(+borderColor/borderStyle), elevation | — | — | Standard shape surface — see IRoundedProps / IBorderProps / IElevationProps. |
padding*, margin* | — | — | Standard spacing surface — see IPaddingProps / IMarginProps. |
<OrigamBreadcrumbItem>
ts
interface IBreadcrumbItemProps extends ICommonsComponentProps, ITagProps,
IBorderProps, IPaddingProps, IMarginProps, IRoundedProps, ILinkProps,
IColorProps, IBgColorProps, IDensityProps, IAdjacentProps,
IHoverProps, IActiveProps {
title: string
disabled?: boolean
}| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Crumb label, rendered via the default slot fallback. |
disabled | boolean | — | Also forced true on the last item by the parent <OrigamBreadcrumb>. Sets pointer-events: none and dims opacity. |
tag | string | 'span' | Root element — overridden to an <a> internally by useLink when href/to resolves to a link. |
href / to / replace / exact | — | — | Standard link surface — see ILinkProps. When present, aria-current="page" is set if the resolved route/active state matches. |
prependIcon / prependAvatar / appendIcon / appendAvatar | — | — | Standard adjacent surface — see IAdjacentProps. |
color / bgColor | TColor | — | Resolved against the parent's <OrigamBreadcrumb>-level defaults when unset — via <OrigamDefaultsProvider> (ADR-005: no component calls useDefaults() any more, this one included). |
density | TDensity | 'default' | Resolved against the parent's default when unset. |
hover / active | boolean | IHoverState / boolean | IActiveState | — | Resolved against the parent's default when unset. |
activeClass | string | — | Custom class applied while isActive (own or route-matched) is true. |
rounded, border | — | — | Standard shape surface. |
padding*, margin* | — | — | Standard spacing surface. |
<OrigamBreadcrumbDivider>
ts
interface IBreadcrumbDividerProps extends ICommonsComponentProps, ITagProps,
IPaddingProps, IMarginProps, IDensityProps, IColorProps, IBgColorProps,
ISizeProps {
divider: string | TIcon
}| Prop | Type | Default | Description |
|---|---|---|---|
divider | string | TIcon | '/' | Required. Rendered as literal text unless it matches a known MDI_ICONS value, in which case an <origam-icon> is rendered instead. |
tag | string | 'span' | Root element/component. |
size | TSize | number | — | Standard size surface — see ISizeProps. |
color / bgColor | TColor | — | Not resolved against the parent <OrigamBreadcrumb> — slotDefaults only targets origam-breadcrumb-item, so <OrigamBreadcrumbDivider> gets no <OrigamDefaultsProvider> entry, unlike <OrigamBreadcrumbItem>. |
padding*, margin* | — | — | Standard spacing surface. |
Anatomy
html
<nav class="origam-breadcrumb" aria-label="Breadcrumb">
<ol class="origam-breadcrumb__items">
<li class="origam-breadcrumb__item">
<a class="origam-breadcrumb-item origam-breadcrumb-item--link">Home</a>
<span class="origam-breadcrumb-divider">/</span>
</li>
<li class="origam-breadcrumb__item">
<span class="origam-breadcrumb-item origam-breadcrumb-item--disabled"
aria-current="page">Current</span>
</li>
</ol>
</nav>Each crumb renders as a single <li class="origam-breadcrumb__item"> that holds the crumb and the divider following it — there is no dedicated <li> for the divider (OrigamBreadcrumb.vue, lines 17-45). The last crumb has no divider inside its <li>.
Design tokens consumed
<OrigamBreadcrumb> reads its variables from packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/) — root surface only, under the --origam-breadcrumb---* prefix. OrigamBreadcrumbItem and OrigamBreadcrumbDivider are separate, independently-shipped components — each now has its own top-level namespace in the same stylesheets, --origam-breadcrumb-item---* and --origam-breadcrumb-divider---* (#386), matching each component's own scoped <style> reads. Before #386 these were nested BEM children of breadcrumb (--origam-breadcrumb__item---*), a name neither component ever read — the fix moved the DTCG source to match the component's own naming, per the project's "one component, one namespace" convention (Origam{PascalCase}.vue files each get their own top-level component-token block; BEM-child naming is reserved for DOM parts that are not separate components).
| CSS variable | Token reference | Consumed by |
|---|---|---|
--origam-breadcrumb---background | transparent | <OrigamBreadcrumb> root |
--origam-breadcrumb---color | {color.text.primary} | <OrigamBreadcrumb> root |
--origam-breadcrumb---border-radius | {radius.none} | <OrigamBreadcrumb> root |
--origam-breadcrumb---border-radius-rounded | {radius.2xl} (24px) | ✅ read by the --rounded modifier since the #607 pass. It was previously {radius.sm} (4px) and unread — the modifier hardcoded var(--origam-radius---2xl, 24px). The token was repointed to 2xl so wiring it changes no pixel: 24px is what --rounded has always rendered. Nobody could have seen the 4px value, because nothing ever read it |
--origam-breadcrumb---box-shadow-elevated | {shadow.md} | ✅ read by the --elevated modifier, with var(--origam-shadow---md, …) as fallback |
--origam-breadcrumb---padding-block / -inline | {space.2} | ✅ read — the component's local --origam-breadcrumb---padding-{block,inline}-{start,end} resolve var(--origam-breadcrumb---padding-{block,inline}, 8px) |
--origam-breadcrumb---line-height | 1.6 | ✅ read by .origam-breadcrumb__items (line-height). Default 1.6 reproduces the previous hardcoded value, so no pixel changes; set it (e.g. 1.55) to follow the theme typography |
--origam-breadcrumb---gap | {space.0} | Generated in main.css, but not read anywhere — &__items has no gap declaration; crumbs are only spaced by the divider's own inline padding |
--origam-breadcrumb-item---hover-color | {color.action.primary.bg} | Generated, but not read anywhere in OrigamBreadcrumbItem.vue — no naming issue this time, the property is simply never wired |
--origam-breadcrumb-item---active-color | {color.text.secondary} | Same — generated, never read |
--origam-breadcrumb-item---opacity-disabled | {opacity.50} | ✅ reaches .origam-breadcrumb-item--disabled via var(--origam-breadcrumb-item---opacity-disabled, 0.5) — one of the two channels #386 actually restored |
--origam-breadcrumb-divider---character | '/' | Generated, but not read — the divider glyph is rendered as template text (), not driven by this CSS variable at all |
--origam-breadcrumb-divider---padding-inline | {space.2} | ✅ reaches the divider via var(--origam-breadcrumb-divider---padding-inline, 8px) — the other channel #386 restored |
--origam-breadcrumb---home-icon-color | {color.action.primary.bg} | optional home icon (via prependIcon on the first item) |
Le recouvrement scopé est corrigé (#607). Les trois composants redéclaraient dans leur bloc
<style scoped>des tokens déjà déclarés parlight.css/dark.css. Un sélecteur scopé —.origam-breadcrumb-item[data-v-xxx], spécificité (0,2,0) — bat:root/[data-theme]à (0,1,0) : la valeur du thème était calculée puis écrasée, quel que soit le nom du token. #386 avait corrigé le NOM ; il ne pouvait rien contre le recouvrement.27 des 30 tokens concernés sont maintenant atteignables par un thème (9 sur la racine, 9 sur l'item, 9 sur le séparateur). Vérifié en A/B contre Chromium :
packages/tests/e2e/breadcrumb-theme-channel.spec.tséchoue sur le code d'avant et passe après.Sur la couleur : aucun pixel ne bouge.
--origam-breadcrumb-item---coloret--origam-breadcrumb-divider---colorétaient déclaréesvar(--…---color-token, inherit)dans le bloc scopé. On pouvait croire à un héritage depuis un ancêtre arbitraire ; ce n'en est pas un.inheritsur une custom property reprend la valeur du parent pour cette même property — or celle-ci est déclarée sur:rootet hérite jusqu'en bas.inheritrésolvait donc déjà le token.Vérifié en A/B dans Chromium, avant et après le dé-shadowage :
avant après item #0a0a0a#0a0a0aséparateur #525252#525252Le séparateur n'est pas devenu plus clair : il rendait déjà
{color.text.secondary}. Ce que la correction change n'est pas la couleur rendue, c'est qu'un thème peut désormais l'écraser — le bloc scopé, à (0,2,0), gagnait auparavant contre:rootà (0,1,0).Plus aucun token n'est recouvert sur ces trois composants : les
transition-durationl'étaient encore, ils ont été repris avec la correction du raccourci (voir « Transitions » ci-dessous).
Transitions
Les trois composants animent transform et color, chacun avec sa propre durée et l'easing du DS :
css
--origam-breadcrumb---transition:
transform var(--origam-breadcrumb---transition-duration-transform) var(--origam-breadcrumb---transition-timing-function),
color var(--origam-breadcrumb---transition-duration-color) var(--origam-breadcrumb---transition-timing-function);| token | valeur | rôle |
|---|---|---|
--origam-{cmp}---transition-duration-transform | {motion.duration.medium} — 200 ms | durée de transform |
--origam-{cmp}---transition-duration-color | {motion.duration.fast} — 100 ms | durée de color |
--origam-{cmp}---transition-timing-function | {motion.easing.standard} | courbe, commune aux deux |
Les deux durées sont thémables séparément, ce qu'un couple dans une seule variable ne permettait pas.
⛔ Ce que cette correction a réparé (#607) — changement visible
Le raccourci était malformé, et le défaut était invisible parce qu'il ne produisait ni erreur ni avertissement. La composition d'origine était :
css
--origam-breadcrumb---transition-property: transform, color;
--origam-breadcrumb---transition-duration: 0.2s, 0.1s;
--origam-breadcrumb---transition: var(…property) var(…duration) var(…timing);Une fois substitué : transform, color 0.2s, 0.1s cubic-bezier(…). transition étant une liste de transitions séparées par des virgules, le navigateur y lisait trois entrées, pas deux propriétés à deux durées. Style calculé mesuré dans Chromium, identique sur les trois composants :
transition-property : transform, color, all
transition-duration : 0s, 0.2s, 0.1s
transition-timing-function : ease, ease, cubic-bezier(0.4, 0, 0.2, 1)| entrée | avant | après |
|---|---|---|
transform | 0 s — jamais animé | 200 ms, easing du DS |
color | 200 ms en ease (pas l'easing du DS) | 100 ms, easing du DS |
all | 100 ms sur TOUTES les propriétés — entrée fantôme | supprimée |
Trois changements visibles, assumés. Le fond, le rayon, l'ombre et l'opacité n'ont plus d'animation d'entrée : elle provenait de l'entrée all, née d'une virgule mal placée, que personne n'avait demandée. transform s'anime enfin, et color prend la courbe du DS.
Le rythme « 200 ms / 100 ms » que décrivait l'ancienne configuration n'a jamais été rendu tel quel — il est désormais réel.
Accessibility
<OrigamBreadcrumb>rendersaria-label="Breadcrumb"by default, translated via the DS'suseLocale()(t('origam.breadcrumb.ariaLabel', 'Breadcrumb')).- The crumb list is a real
<ol>/<li>structure — screen readers announce it as an ordered list of navigation links. - The current page's crumb carries
aria-current="page"andpointer-events: none(via the--disabledmodifier). <OrigamBreadcrumbDivider>is decorative; it carries noaria-hiddenattribute of its own, so a text divider (e.g./) is read aloud by screen readers between crumbs — worth keeping in mind if you switch to a purely visual glyph divider.
Theming notes
- The component is theme-aware out of the box for the root surface (background, color, radius, elevation). Switching
<html data-theme="…">re-resolves those variables instantly. - Item/divider-level tokens: the naming drift is fixed (#386), but most properties remain unreachable due to local shadowing — see the note under "Design tokens consumed".
- A sub-tree can opt into a different theme via
<OrigamThemeProvider>.
Related
OrigamIcon— renders the divider glyph whendividermatches an MDI icon id, and the item'sprependIcon/appendIcon.OrigamAvatar— renders the item'sprependAvatar/appendAvatar.