Breadcrumb

The trail back up from the page being read. It is data-driven: one list of segments, and the current one is worked out from the address rather than marked by hand.

Usage

vue

<script setup lang="ts">
import { VBreadcrumb } from 'vectis-ui'

const items = [
  { label: 'Home', href: '/app' },
  { label: 'Projects', href: '/app/projects' },
  { label: 'Vectis UI', href: '/app/projects/vectis-ui' },
]
</script>

<template>
  <VBreadcrumb :items="items" current-path="/app/projects/vectis-ui" />
</template>

Examples

Custom separator

separatorIcon replaces the chevron drawn between two segments, and takes any icon value.

vue

<script setup lang="ts">
import { VBreadcrumb } from 'vectis-ui'
import { arrow_right_alt as arrowRightAlt } from 'vectis-ui/icons'

import slash from '~/assets/img/breadcrumb-slash.svg'

const items = [
  { label: 'Home', href: '/app' },
  { label: 'Projects', href: '/app/projects' },
  { label: 'Vectis UI', href: '/app/projects/vectis-ui' },
]
</script>

<template>
  <VBreadcrumb
    :items="items"
    current-path="/app/projects/vectis-ui"
    :separator-icon="arrowRightAlt"
    label="Trail with an icon separator"
  />

  <VBreadcrumb
    :items="items"
    current-path="/app/projects/vectis-ui"
    :separator-icon="{ src: slash }"
    label="Trail with an image separator"
  />
</template>

With icons

Each segment takes an icon, decorative beside the label a screen reader reads.

vue

<script setup lang="ts">
import { VBreadcrumb } from 'vectis-ui'
import {
  cloud_upload as cloudUpload,
  picture_as_pdf as pictureAsPdf,
  table_chart as tableChart,
} from 'vectis-ui/icons'

const items = [
  { label: 'Uploads', href: '/app/files', icon: cloudUpload },
  { label: 'Reports', href: '/app/files/reports', icon: tableChart },
  { label: 'Third quarter', href: '/app/files/reports/q3', icon: pictureAsPdf },
]
</script>

<template>
  <VBreadcrumb :items="items" current-path="/app/files/reports/q3" />
</template>

Truncation

Past maxItems, the trail keeps its first segment and its last two, and folds the rest behind an ellipsis opening a menu of the hidden segments.

vue

<script setup lang="ts">
import { VBreadcrumb } from 'vectis-ui'

const items = [
  { label: 'Home', href: '/app' },
  { label: 'Projects', href: '/app/projects' },
  { label: 'Vectis UI', href: '/app/projects/vectis-ui' },
  { label: 'Components', href: '/app/projects/vectis-ui/components' },
  { label: 'Breadcrumb', href: '/app/projects/vectis-ui/components/breadcrumb' },
  { label: 'Accessibility', href: '/app/projects/vectis-ui/components/breadcrumb/a11y' },
]
</script>

<template>
  <VBreadcrumb
    :items="items"
    current-path="/app/projects/vectis-ui/components/breadcrumb/a11y"
    :max-items="4"
  />
</template>

API

Props

Prop	Type	Default
`items`	`BreadcrumbItem[]`	none
The segments of the trail, ordered from the most general down to the deepest.
`label`	`string`	none
The name screen readers announce for this navigation. It falls back to the design system dictionary, in the current language.
`currentPath`	`string`	none
The address of the page being displayed. The segment whose `href` matches it is the current one, even when it is folded into the menu. A trailing slash, a query and a hash on either side make no difference, so a router's full path can be passed as is.
`separatorIcon`	`IconSource`	`chevron_right`
The icon drawn between two segments. It is mirrored in a right-to-left page.
`maxItems`	`number`	none
The length past which the trail folds: only the first segment, an ellipsis button and the last two remain, the button opening a menu that lists the hidden segments alone. Below 3 there would be nothing left to fold, so 3 is the effective minimum.
`ellipsisLabel`	`string`	none
The name screen readers announce for the ellipsis button. It falls back to the design system dictionary.

Types

The types the tables above name, written as the library declares them. The ones carrying export can be imported from vectis-ui to type your own code; the others are the shape of what a slot hands out.

export interface BreadcrumbItem {
  label: string
  href: string
  icon?: IconSource
}

export interface BuiltinIcon {
  name: string
  paths: readonly [string] | readonly [string, string]
}

export type IconRender =
  | { path: string; viewBox?: string }
  | { component: Component; props?: Record<string, unknown> }
  | { src: string }
  | { text: string; class?: string }
  | { class: string }

export type IconSource = string | BuiltinIcon | IconRender