createBreadcrumbs

A composable that extends createSingle for breadcrumb navigation with automatic path truncation.

Copy Page as Markdown

Intermediate98.7% coverageFeb 18, 2026

Usage

The createBreadcrumbs composable manages an ordered path of items. When you select an earlier item, everything after it is removed. Use values() to iterate the current trail for rendering.

Depth: 6 · At root: false

<script setup lang="ts">
  import { computed } from 'vue'
  import { createBreadcrumbs } from '@vuetify/v0'

  const breadcrumbs = createBreadcrumbs()

  const path = [
    { text: 'Home' },
    { text: 'Documents' },
    { text: 'Projects' },
    { text: 'Vuetify' },
    { text: 'Components' },
    { text: 'Breadcrumbs' },
  ]

  breadcrumbs.onboard(path)

  const items = computed(() => breadcrumbs.values())

  function reset () {
    breadcrumbs.clear()
    breadcrumbs.onboard(path)
  }
</script>

<template>
  <div class="space-y-4">
    <nav class="flex items-center gap-1.5 text-sm">
      <template
        v-for="(ticket, i) in items"
        :key="ticket.id"
      >
        <span v-if="i > 0" class="text-on-surface-variant">/</span>

        <button
          class="text-primary hover:underline cursor-pointer"
          @click="breadcrumbs.select(ticket.id)"
        >
          {{ ticket.text }}
        </button>
      </template>
    </nav>

    <div class="flex items-center gap-3 text-xs text-on-surface-variant">
      <span>
        Depth: {{ breadcrumbs.depth.value }} &middot;
        At root: {{ breadcrumbs.isRoot.value }}
      </span>

      <button
        class="text-primary hover:underline cursor-pointer"
        @click="reset"
      >
        Reset
      </button>
    </div>
  </div>
</template>

Architecture

createBreadcrumbs extends createSingle with path truncation and derived navigation state:

The Breadcrumbs component consumes createBreadcrumbs as its backing model, similar to how Tabs.Root uses createStep.

Reactivity

Breadcrumb state is always reactive. All derived properties update automatically when items are registered, unregistered, or navigated.

Property/Method	Reactive	Notes
`depth`		Ref — count of registered items
`isRoot`		Ref — `depth <= 1`
`isEmpty`		Ref — `depth === 0`
`selectedId`		Computed — current (last) item ID
`selectedItem`		Computed — current item ticket
`selectedValue`		Computed — current item value
`selectedIndex`		Computed — current item position

Tip

Depth tracking Use depth, isRoot, and isEmpty to conditionally render navigation controls like a “Back” button or hide the breadcrumb trail when at the root level.

A file explorer that uses createBreadcrumbs to track the user’s position in a folder tree. Clicking a folder calls register() to push it onto the trail, while clicking a breadcrumb calls select() to navigate back — automatically truncating everything after the selected crumb.

File breakdown:

File	Role
`file-explorer.vue`	Interactive file browser with breadcrumb navigation and back button
`tree.ts`	Typed folder tree data and `FolderNode` interface

Key patterns:

FileBreadcrumbTicketInput extends BreadcrumbTicketInput<FolderNode> so selectedValue is properly typed — no casting needed
Each folder node is stored as the ticket’s value, keeping the breadcrumb trail and folder listing in sync through the registry itself
isRoot controls whether the back button is visible

Drill into Home > Documents > Projects > v0-app > src to see the trail grow, then click an earlier crumb to truncate back.

Depth: 1 · At root: true

API Reference

The following API details are for the createBreadcrumbs composable.

Functions

createBreadcrumbs

(options?: BreadcrumbsOptions) => R

Creates a breadcrumbs navigation model.

createBreadcrumbsContext

(_options?: BreadcrumbsContextOptions) => ContextTrinity<R>

Creates a breadcrumbs context for dependency injection.

useBreadcrumbs

(namespace?: string) => R

Returns the current breadcrumbs instance from context.

Options

events

boolean

Enable event emission for registry operations

Default: false

reactive

boolean

Enable reactive behavior for registry operations

Default: false

disabled

MaybeRefOrGetter<boolean>

When true, the entire selection instance is disabled.

enroll

MaybeRefOrGetter<boolean>

When true, newly registered items are automatically selected if not disabled. Useful for pre-selecting items in multi-select scenarios.

mandatory

MaybeRefOrGetter<boolean | "force">

Controls mandatory selection behavior: - `false` (default): No mandatory selection enforcement - `true`: Prevents deselecting the last selected item (user must always have one selected) - `'force'`: Automatically selects the first non-disabled item on registration

multiple

MaybeRefOrGetter<boolean>

When true, treats the selection as an array

Properties

collection

ReadonlyMap<ID, Z>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of selected ticket IDs

selectedItems

ComputedRef<Set<E>>

Set of selected ticket instances

selectedValues

ComputedRef<Set<unknown>>

Set of selected ticket values

disabled

MaybeRef<boolean>

Disable state for the entire selection instance

selectedId

ComputedRef<any>

selectedIndex

ComputedRef<number>

selectedItem

ComputedRef<E>

selectedValue

ComputedRef<E["value"]>

depth

Readonly<Ref<number, number>>

Number of items in the path

isRoot

Readonly<Ref<boolean, boolean>>

Whether at root level (depth <= 1)

isEmpty

Readonly<Ref<boolean, boolean>>

Whether path is empty (depth === 0)

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: Z["value"]) => ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

lookup a ticket by index number

get

(id: ID) => Z | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>) => Z

Update or insert a ticket by ID

values

() => readonly Z[]

Get all values of registered tickets

entries

() => readonly [ID, Z][]

Get all entries of registered tickets

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => Z | undefined

Seek for a ticket based on direction and optional predicate

on

<K extends Extensible<RegistryEventName>>(event: K, cb: EventHandler<Z, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: EventHandler<Z, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<Z, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

offboard

(ids: ID[]) => void

Offboard multiple tickets at once

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Clear all selected IDs and reindexes

unselect

(id: ID) => void

Unselect a ticket by ID (Toggle OFF)

toggle

(id: ID) => void

Toggles a ticket ON and OFF by ID

selected

(id: ID) => boolean

Check if a ticket is selected by ID

mandate

() => void

Mandates selected ID based on "mandatory" Option

register

(ticket?: Partial<Z>) => E

onboard

(registrations: Partial<Z>[]) => E[]

Onboard multiple tickets at once

first

() => void

Navigate to root (first item)

() => void

Navigate up one level (remove last item)

select

(id: ID) => void

Navigate to specific item by id (truncates path)