Breadcrumb - Vize

Accessible, unstyled breadcrumb navigation primitive for route hierarchies.


Package	`@vizejs/ui/breadcrumb`
Maturity	stable
Own the source	`vize lib pull breadcrumb`
Requires	—
Aliases	breadcrumb navigation, route breadcrumb, path trail, hierarchy trail
Covers	HTML nav landmark, WAI-ARIA breadcrumb pattern, React Aria Breadcrumbs

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { Breadcrumb, BreadcrumbRoot, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator } from "@vizejs/ui/breadcrumb";

Or copy the source into your project with vize lib pull breadcrumb (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Documentation breadcrumb trail whose last link marks the current page. -->
<script setup lang="ts">
import {
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbRoot,
  BreadcrumbSeparator,
} from "@vizejs/ui/breadcrumb";
</script>

<template>
  <BreadcrumbRoot label="Documentation path">
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Home</BreadcrumbLink>
        <BreadcrumbSeparator>/</BreadcrumbSeparator>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
        <BreadcrumbSeparator>/</BreadcrumbSeparator>
      </BreadcrumbItem>
      <BreadcrumbItem>
        <BreadcrumbLink href="/docs/components">Components</BreadcrumbLink>
        <BreadcrumbSeparator>/</BreadcrumbSeparator>
      </BreadcrumbItem>
      <BreadcrumbItem current>
        <BreadcrumbLink href="/docs/components/breadcrumb" current="page"
          >Breadcrumb</BreadcrumbLink
        >
      </BreadcrumbItem>
    </BreadcrumbList>
  </BreadcrumbRoot>
</template>

API

`Breadcrumb`

Source: src/families/navigation/breadcrumb/breadcrumb.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"nav"`	Native element, custom element, or component to render.
`label`	`string`	`"Breadcrumb"`	Accessible landmark label mirrored to `aria-label`.

Slots

Slot	Slot props	Description
`default`	`BreadcrumbRootSlotState`	Renders breadcrumb list content with the resolved landmark label.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`label`	—

`BreadcrumbRoot`

Source: src/families/navigation/breadcrumb/breadcrumb.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"nav"`	Native element, custom element, or component to render.
`label`	`string`	`"Breadcrumb"`	Accessible landmark label mirrored to `aria-label`.

Slots

Slot	Slot props	Description
`default`	`BreadcrumbRootSlotState`	Renders breadcrumb list content with the resolved landmark label.

Exposed

Member	Type	Description
`label`	`string`	Accessible landmark label mirrored to `aria-label`.
`element`	`PrimitiveElement \| null`	Rendered landmark element or component instance.

`BreadcrumbItem`

Source: src/families/navigation/breadcrumb/breadcrumb-item.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"li"`	Native element, custom element, or component to render.
`current`	`boolean`	`false`	Whether this item represents the current route segment.

Slots

Slot	Slot props	Description
`default`	`BreadcrumbItemSlotState`	Renders item contents with current-route state.

Exposed

Member	Type	Description
`current`	`boolean`	Whether this breadcrumb item represents the current page, step, or location.
`element`	`PrimitiveElement \| null`	Rendered list item element or component instance.

`BreadcrumbLink`

Source: src/families/navigation/breadcrumb/breadcrumb-link.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"a"`	Native element, custom element, or component to render.
`current`	`BreadcrumbCurrent \| false`	`false`	Current route state. `true` resolves to `aria-current="page"`.
`href`	`string`	`undefined`	Native link destination. Router components can receive their own route attrs.

Slots

Slot	Slot props	Description
`default`	`BreadcrumbLinkSlotState`	Renders link content with resolved current-route state.

Exposed

Member	Type	Description
`current`	`boolean`	Whether this link represents the current page, step, or location.
`ariaCurrent`	`Exclude<BreadcrumbCurrent, true> \| undefined`	Resolved `aria-current` value, or `undefined` when the link is not current.
`element`	`PrimitiveElement \| null`	Rendered link element or component instance.
`focus`	`(options?: FocusOptions) => void`	Focus the rendered link when it is a native HTMLElement.

`BreadcrumbList`

Source: src/families/navigation/breadcrumb/breadcrumb-list.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"ol"`	Native element, custom element, or component to render.

Slots

Slot	Slot props	Description
`default`	—	Renders ordered breadcrumb items.

Exposed

Member	Type	Description
`element`	`PrimitiveElement \| null`	Rendered list element or component instance.

`BreadcrumbSeparator`

Source: src/families/navigation/breadcrumb/breadcrumb-separator.vue

Props

Prop	Type	Default	Description
`as`	`PrimitiveAs`	`"span"`	Native element, custom element, or component to render.

Slots

Slot	Slot props	Description
`default`	`BreadcrumbSeparatorSlotState`	Renders decorative separator content hidden from assistive technology.

Exposed

Member	Type	Description
`decorative`	`true`	Separators are always decorative and hidden from assistive technology.
`element`	`PrimitiveElement \| null`	Rendered separator element or component instance.

Behavior

Breadcrumb provides a headless landmark and ordered-list shell for route hierarchies. It owns the accessibility invariants while leaving link rendering, router integration, separators, truncation, and visual styling to consumers.

Contract	Observable behavior
Landmark	`breadcrumb.vue` renders a `nav` by default, applies `data-vize-ui="breadcrumb"` and `part="root"`, and mirrors `label` to `aria-label`.
List semantics	`breadcrumb-list.vue` renders an `ol` by default, applies `data-vize-ui="breadcrumb-list"` and `part="list"`, and does not add roles or styles.
Item state	`breadcrumb-item.vue` renders an `li` by default, applies `data-vize-ui="breadcrumb-item"` and `part="item"`, and mirrors current state to `data-current="true"` only when current.
Link state	`breadcrumb-link.vue` renders an `a` by default, forwards `href`, applies `data-vize-ui="breadcrumb-link"` and `part="link"`, and maps `current=true` to `aria-current="page"`.
Link safety	`BreadcrumbLink` trims safe `href` values and suppresses empty, control-character, `data:`, `javascript:`, and `vbscript:` destinations.
Route-aware current	`BreadcrumbLink current` accepts the literal `aria-current` route states `page`, `step`, `location`, `date`, and `time`, preserving strict type feedback for router-derived state.
Separator semantics	`breadcrumb-separator.vue` renders a `span` by default, applies `data-vize-ui="breadcrumb-separator"` and `part="separator"`, and is always `aria-hidden="true"` with `role="presentation"`.
Slots	Root, item, link, and separator slots receive typed state objects for label, current state, resolved `aria-current`, and decorative separator state.
Expose	Every part exposes its rendered element; root exposes `label`, item exposes `current`, link exposes `current`, `ariaCurrent`, and `focus`, and separator exposes `decorative`.
Styling	The primitive emits no class names, inline styles, CSS custom properties, or package CSS; spacing, glyphs, collapse, ellipsis, color, and focus rings are consumer-owned.
SSR	Repeated isolated SSR requests emit byte-identical markup, and hydration preserves the server root without warnings or node replacement.