Skip to content
Kimenpre-v1documentation home
Color scheme

ki-breadcrumb

Use ki-breadcrumb to show how the current page fits into a workspace, app, or documentation hierarchy. Add one direct ki-breadcrumb-item for each level, from the root to the page the reader is on.

Theme for this example
Color scheme for this example
Workspace Projects Settings
<ki-breadcrumb label="Project path">
<ki-breadcrumb-item href="#workspace">Workspace</ki-breadcrumb-item>
<ki-breadcrumb-item href="#projects">Projects</ki-breadcrumb-item>
<ki-breadcrumb-item current>Settings</ki-breadcrumb-item>
</ki-breadcrumb>

Each item’s text supplies its label. Ancestors with an href are links. The last item appears as text and is announced as the current page, with or without the explicit current marker.

Long paths

Set max-items="4" to collapse a long path. When the path exceeds the threshold, the first and last two levels stay visible and the middle levels appear in the ellipsis menu. A positive limit below four uses four.

Theme for this example
Color scheme for this example
Workspace Projects Kimen Packages Releases v2.4.0
<ki-breadcrumb label="Release path" max-items="4">
<ki-breadcrumb-item href="#workspace">Workspace</ki-breadcrumb-item>
<ki-breadcrumb-item href="#projects">Projects</ki-breadcrumb-item>
<ki-breadcrumb-item href="#kimen">Kimen</ki-breadcrumb-item>
<ki-breadcrumb-item href="#packages">Packages</ki-breadcrumb-item>
<ki-breadcrumb-item href="#releases">Releases</ki-breadcrumb-item>
<ki-breadcrumb-item current>v2.4.0</ki-breadcrumb-item>
</ki-breadcrumb>

Tab reaches the visible links and the ellipsis button. Enter, Space and Down open the menu at its first level. Up opens it at its last level. Move through the menu with the arrow keys, Home and End, or a level’s first character. Escape closes the menu and returns focus to the button.

Localization and density

Set label to name the navigation landmark. Use more-label to localize the overflow button and put {n} where the hidden level count belongs. Right-to-left reading order follows the nearest dir setting. Use data-ki-density="touch" on the breadcrumb or its region for larger targets.

API reference

When to use: show the current page in a deeper hierarchy using direct ki-breadcrumb-item children ordered from root to current.

When not to use: switch between peer routes, toggle peer panels, or display progress through a form.

Properties & attributes

AttributePropertyTypeDefaultDescription
labellabelstring'Breadcrumb'Accessible name of the navigation landmark.
max-itemsmaxItemsnumber | undefined–Optional overflow threshold. Above it, keep the first and last two levels visible. Positive values are rounded down and clamped to four. Omit this prop, or pass a non-positive or non-finite value, to show the full trail.
more-labelmoreLabelstring'Show {n} more levels'Localizable name of the overflow control. Use {n} for the hidden level count.

Slots

SlotDescription
(default)Direct ki-breadcrumb-item children in hierarchy order.

CSS parts

PartDescription
currentThe current page label.
labelThe label of an ancestor with no destination.
linkA visible native ancestor link.
listThe ordered list of visible levels.
list-itemA list entry for a level or the overflow control.
menuThe anchored menu of collapsed levels.
menu-itemA destination or unavailable level in the overflow menu.
more-buttonThe overflow menu button.
navigationThe named navigation landmark.

CSS custom properties

The public styling contract of ki-breadcrumb: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-breadcrumb-bgTransparent backing for ancestor text and the overflow trigger.
--ki-breadcrumb-current-bgTransparent backing for the current level.
--ki-breadcrumb-current-fgEmphasized foreground of the current level.
--ki-breadcrumb-fgMedium-emphasis ink for ancestors and the overflow trigger, strengthened in more-contrast mode.
--ki-breadcrumb-gapGap between breadcrumb rows, levels and their chevrons.
--ki-breadcrumb-glyph-sizeSize of the ellipsis glyph.
--ki-breadcrumb-hover-bgBacking for the active overflow trigger and highlighted overflow links.
--ki-breadcrumb-hover-fgForeground for the active overflow trigger and highlighted overflow links.
--ki-breadcrumb-menu-backdrop-filterComplete backdrop filter of the overflow menu, none by default.
--ki-breadcrumb-menu-bgSurface behind the overflow menu entries.
--ki-breadcrumb-menu-bg-imageOptional image layered over the overflow menu surface.
--ki-breadcrumb-menu-fgText of overflow menu entries.
--ki-breadcrumb-menu-max-block-sizeMaximum block size of the scrollable overflow menu.
--ki-breadcrumb-menu-paddingInset around the overflow menu entries.
--ki-breadcrumb-menu-radiusOuter radius of the overflow menu.
--ki-breadcrumb-menu-shadowElevation of the overflow menu above the page.
--ki-breadcrumb-padding-blockBlock inset of a level label.
--ki-breadcrumb-padding-inlineInline inset of a level label.
--ki-breadcrumb-radiusRadius of the overflow trigger and level focus outlines.
--ki-breadcrumb-separatorForeground of the decorative breadcrumb chevron.
--ki-breadcrumb-separator-sizeEdge length of the decorative chevron before rotation.
--ki-breadcrumb-separator-strokeStroke width of the decorative chevron.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-underline-offsetGap between text and its underline.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-breadcrumb in Storybook