Breadcrumb

A hierarchy of links to navigate through a website.

Usage

Items

Use the items prop as an array of objects with the following properties:

label?: string
icon?: string
avatar?: AvatarProps
class?: any
slot?: string

You can also pass any property from the Link component such as to, target, etc.

<script setup lang="ts">
const items = ref([
  {
    label: 'Home',
    icon: 'i-lucide-house'
  },
  {
    label: 'Components',
    icon: 'i-lucide-box',
    to: '/components'
  },
  {
    label: 'Breadcrumb',
    icon: 'i-lucide-link',
    to: '/components/breadcrumb'
  }
])
</script>

<template>
  <UBreadcrumb :items="items" />
</template>

A span is rendered instead of a link when the to property is not defined.

Separator Icon

Use the separator-icon prop to customize the Icon between each item. Defaults to i-lucide-chevron-right.

separatorIcon

<script setup lang="ts">
const items = ref([
  {
    label: 'Home',
    icon: 'i-lucide-house'
  },
  {
    label: 'Components',
    icon: 'i-lucide-box',
    to: '/components'
  },
  {
    label: 'Breadcrumb',
    icon: 'i-lucide-link',
    to: '/components/breadcrumb'
  }
])
</script>

<template>
  <UBreadcrumb separator-icon="i-lucide-arrow-right" :items="items" />
</template>

You can customize this icon globally in your app.config.ts under ui.icons.chevronRight key.

Examples

With separator slot

Use the #separator slot to customize the separator between each item.

<script setup lang="ts">
const items = [{
  label: 'Home',
  to: '/'
}, {
  label: 'Components',
  to: '/components'
}, {
  label: 'Breadcrumb',
  to: '/components/breadcrumb'
}]
</script>

<template>
  <UBreadcrumb :items="items">
    <template #separator>
      <span class="mx-2 text-[var(--ui-text-muted)]">/</span>
    </template>
  </UBreadcrumb>
</template>

With custom slot

Use the slot property to customize a specific item.

You will have access to the following slots:

#{{ item.slot }}
#{{ item.slot }}-leading
#{{ item.slot }}-label
#{{ item.slot }}-trailing

<script setup lang="ts">
const items = [{
  label: 'Home',
  to: '/'
}, {
  slot: 'dropdown',
  icon: 'i-lucide-ellipsis',
  children: [{
    label: 'Documentation'
  }, {
    label: 'Themes'
  }, {
    label: 'GitHub'
  }]
}, {
  label: 'Components',
  to: '/components'
}, {
  label: 'Breadcrumb',
  to: '/components/breadcrumb'
}]
</script>

<template>
  <UBreadcrumb :items="items">
    <template #dropdown="{ item }">
      <UDropdownMenu :items="item.children">
        <UButton :icon="item.icon" color="neutral" variant="link" class="p-0.5" />
      </UDropdownMenu>
    </template>
  </UBreadcrumb>
</template>

You can also use the #item, #item-leading, #item-label and #item-trailing slots to customize all items.

API

Props

Prop	Default	Type
`as`	`"nav"`	`any` The element or component this component should render as.
`items`		`BreadcrumbItem[]`
`separatorIcon`	`appConfig.ui.icons.chevronRight`	`string` The icon to use as a separator.
`labelKey`	`"label"`	`string` The key used to get the label from the item.
`ui`		`PartialString<{ root: string; list: string; item: string; link: string; linkLeadingIcon: string; linkLeadingAvatar: string; linkLeadingAvatarSize: string; linkLabel: string; separator: string; separatorIcon: string; }>`

Slots

Slot	Type
`item`	`{ item: BreadcrumbItem; index: number; active?: boolean \| undefined; }`
`item-leading`	`{ item: BreadcrumbItem; index: number; active?: boolean \| undefined; }`
`item-label`	`{ item: BreadcrumbItem; index: number; active?: boolean \| undefined; }`
`item-trailing`	`{ item: BreadcrumbItem; index: number; active?: boolean \| undefined; }`
`separator`	`{}`

Theme

app.config.ts

export default defineAppConfig({
  ui: {
    breadcrumb: {
      slots: {
        root: 'relative min-w-0',
        list: 'flex items-center gap-1.5',
        item: 'flex min-w-0',
        link: 'group relative flex items-center gap-1.5 text-sm min-w-0 focus-visible:outline-[var(--ui-primary)]',
        linkLeadingIcon: 'shrink-0 size-5',
        linkLeadingAvatar: 'shrink-0',
        linkLeadingAvatarSize: '2xs',
        linkLabel: 'truncate',
        separator: 'flex',
        separatorIcon: 'shrink-0 size-5 text-[var(--ui-text-muted)]'
      },
      variants: {
        active: {
          true: {
            link: 'text-[var(--ui-primary)] font-semibold'
          },
          false: {
            link: 'text-[var(--ui-text-muted)] font-medium'
          }
        },
        disabled: {
          true: {
            link: 'cursor-not-allowed opacity-75'
          }
        },
        to: {
          true: ''
        }
      },
      compoundVariants: [
        {
          disabled: false,
          active: false,
          to: true,
          class: {
            link: [
              'hover:text-[var(--ui-text)]',
              'transition-colors'
            ]
          }
        }
      ]
    }
  }
})

Badge

A short text to represent a status or a category.

Button

A button element that can act as a link or trigger an action.