Breadcrumb

Shows the page hierarchy path; the last item is the current page (aria-current="page").

Basic usage

Basic usage

Example

Item icons

Set the icon field on an items entry to render a leading icon (same registry as oas-icon).

Item icons

Example

Custom separator

separator accepts any text; when the value matches an icon registry name it renders as an icon separator (e.g. chevron-right).

Text separator

Example

Icon separator

Example

Per-item separator

The separator field on an items entry overrides the separator after that item (icon names supported too).

Per-item separator

Example

Real links

Items with href render as native <a> links: clicks do not block the default behavior (native navigation) and still fire oas-select (SPA hosts may intercept for routing). target opens in a new window; _blank automatically adds noopener noreferrer.

Real links

Nothing clicked

Example

Click event

The oas-select event: detail: { value: href }. This example uses href="#" placeholders so clicks show feedback without navigating.

Click event

Nothing clicked

Example

Disabled items

An item with disabled: true renders as non-interactive text (aria-disabled="true"); clicks do not fire events.

Disabled items

Example

Collapse mode

collapsed + max-items: when there are more items than max-items (default 4), the middle items collapse into …; click … to expand a dropdown with all collapsed items .

Collapse mode

Nothing clicked

Example

Collapse retention

items-before-collapse / items-after-collapse control how many items stay visible before and after the collapse ellipsis (defaults: 1 before, max-items - 2 after).

Collapse retention

Example

Custom ellipsis

collapse-text replaces the default … text of the collapse ellipsis.

Custom ellipsis

Example

Collapse expand event

Clicking the collapse ellipsis to expand the dropdown fires oas-collapse-click with detail: { collapsedItems } (the original array of collapsed items) — hosts can draw their own collapse panel; collapsing does not fire it.

Collapse expand event (oas-collapse-click)

Not expanded yet

Example

Declarative child channel

Besides the items JSON, you can write items declaratively with <oas-breadcrumb-item> (the items attribute wins when explicitly set). The default slot text is the label; attributes map to the items fields: href/target/icon/disabled/max-width/separator/dropdown/active. Child additions/removals, attribute and text changes re-render automatically.

Child channel basic

HomeComponentsBreadcrumb

Example

With icons and attributes

HomeComponents (new tab)DeprecatedA rather long breadcrumb item title

Example

Custom separators (child channel)

Place <oas-breadcrumb-separator> between two items; its content can be arbitrary nodes (text / icon / inline elements). The per-item separator attribute accepts text or icon names, and a slot="separator" child element accepts arbitrary nodes.

Standalone separator element

Home→Components›Breadcrumb

Example

Per-item separator (attribute / slot)

HomeComponents·Breadcrumb

Example

Hierarchy indentation visual

The breadcrumb is flat by default; a pure-CSS trick can produce an indented "level" look (hide separators + indent items in order — no API involved). Idea: make ::part(nav) vertical, hide ::part(separator), and increase padding-left on ::part(item):nth-child() by occurrence order.

Hierarchy indentation (pure CSS)

Example

Item with dropdown (oas-dropdown combo)

The dropdown attribute on oas-breadcrumb-item turns the item into a dropdown trigger (link-list menu; selecting an item fires oas-select). Combined with oas-dropdown you get richer menu content; selections from both channels can feed one shared state.

Item with dropdown

HomeMoreBreadcrumb

oas-dropdown combo menu

Nothing selected

Example

Single-line ellipsis

ellipsis: the breadcrumb never wraps; link text is truncated with an ellipsis when the container is narrow, and links keep the full title (hover to see the complete name).

Single-line ellipsis

Example

Per-item width truncation

max-item-width (px) truncates each item globally with an ellipsis + title tooltip; the maxWidth field overrides per item.

Per-item width truncation

Example

Sizes

size presets: small / medium (default) / large.

Sizes

Example

Item dropdowns

The dropdown array on an items entry turns that item into a dropdown trigger (click to expand; selecting a menu item fires oas-select).

Item dropdowns

Nothing clicked

Example

Clickable last item / current semantics

• active: true on an item explicitly marks it as current (aria-current="page" moves there); other items with href remain clickable.
• active-last: the last (current) item stays clickable even with href, while keeping aria-current="page".

Explicit active

Example

Clickable last item (active-last)

Nothing clicked

Example

Keyboard arrow navigation

With focus on any link or the ellipsis button, ← / → cycle focus across items; Home / End jump to the first/last. Esc closes an open dropdown trigger.

Keyboard navigation

Example

Color variants

color sets the semantic color of the current item and link hover (primary / success / warning / danger / info); colors come from tokens (dark variants included).

Color variants

Example

Underline variant

variant="underline": links and the current item are permanently underlined.

Underline variant

Example

Structured data

The component injects schema.org BreadcrumbList JSON-LD into the host's light DOM (<script type="application/ld+json">, only items with href), giving search engines a breadcrumb trail without handwritten microdata.

Structured data

View page source: a script[data-oas-breadcrumb-ld] already exists inside the host.

Example

Edge cases

Empty data

Example

Font Size

Font size follows the outer context (inherited) by default; override with the CSS variable --oas-breadcrumb-font (e.g. 18px).

API

oas-breadcrumb

Attributes

Attribute	Description	Type	Default
active-last	Keep the last item clickable: when the current (last) item has href, render it as a link (still carrying aria-current="page")	boolean	—
collapse-text	Custom text for the collapse ellipsis (default …)	string	…
collapsed	Collapse mode: when there are more items than max-items, middle items collapse into …; click to expand the dropdown	boolean	—
color	Visual variant: the current item and link hover use the specified semantic color (primary/success/warning/danger/info)	string	—
ellipsis	Single-line ellipsis: the breadcrumb never wraps; overflowing link text is truncated with an ellipsis	boolean	—
items	Breadcrumb items JSON: label/href/icon/disabled/target/separator/dropdown/maxWidth/active	string	[]
items-after-collapse	Number of items kept after the collapse ellipsis (default max-items - 2)	string	—
items-before-collapse	Number of items kept before the collapse ellipsis (default 1)	string	—
max-item-width	Global max width per item (px): overflow is truncated with an ellipsis + title tooltip; per-item maxWidth overrides	string	—
max-items	Maximum number of visible items in collapse mode (including …); invalid values fall back to 4	string	4
separator	Separator (supports icon names, e.g. chevron-right)	string	/
size	Size preset: small/medium (default)/large	string	medium
variant	Style variant: underline (links and the current item are permanently underlined)	string	—

Events

Event	Description
oas-collapse-click	Fired when the collapse ellipsis is clicked to expand the dropdown (not fired when collapsing), detail: { collapsedItems } (the original array of collapsed items, for hosts that want a custom collapse panel)
oas-select	A link item, a collapsed dropdown item, or an item dropdown item was clicked; detail: { value: href } (real links do not block default navigation; hosts may intercept for routing)

Slots

Name	Description
separator	Custom separator content (text or icon; replaces the separator attribute)

CSS Variables

CSS Variable	Default
--oas-breadcrumb-font	inherit

oas-breadcrumb-item

Attributes

Attribute	Description	Type	Default
active	Explicitly mark this item as current (aria-current="page"); defaults to the last item	—	—
disabled	Disabled item: rendered as non-interactive text (aria-disabled)	—	—
dropdown	Link-list dropdown for the item (JSON, e.g. [{"label":"Child","href":"/a"}]); the item renders as a dropdown trigger	—	—
href	Link URL: with href the item renders as a native <a> (real navigation + still fires oas-select)	—	—
icon	Leading icon (@oas-ui/icons registry icon name)	—	—
max-width	Per-item max width (px): overflow is truncated with an ellipsis + title tooltip	—	—
separator	Per-item separator: overrides the global separator (text or icon name); a slot="separator" child element also accepts arbitrary nodes	—	—
target	Link target (_blank automatically adds noopener noreferrer)	—	—

Slots

Name	Description
default	Breadcrumb item label content (default slot text)

oas-breadcrumb-separator

Slots

Name	Description
default	Separator content: arbitrary nodes (text / icon / inline elements)

nav + aria-label="Breadcrumb", the last item has aria-current="page" and is not clickable.