createBreadcrumbs

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

Copy Markdown

Preview Intermediate Jun 29, 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 { toRef } from 'vue'
  import { createBreadcrumbs, useProxyRegistry } from '@vuetify/v0'

  const breadcrumbs = createBreadcrumbs()
  const proxy = useProxyRegistry(breadcrumbs)

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

  breadcrumbs.onboard(path)

  const items = toRef(() => proxy.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>

Context / DI

Use createBreadcrumbsContext to share a breadcrumbs instance across a component tree:

import { createBreadcrumbsContext } from '@vuetify/v0'

export const [useBreadcrumbs, provideBreadcrumbs, breadcrumbs] =
  createBreadcrumbsContext({ namespace: 'my:breadcrumbs' })

// In parent component
provideBreadcrumbs()

// In child component
const nav = useBreadcrumbs()
nav.register({ text: 'Settings' })

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.