---
title: "useBreadcrumbItems()"
description: "A composable used to display a breadcrumb list that helps users to navigate between pages."
canonical_url: "https://nuxtseo.com/docs/seo-utils/api/breadcrumbs"
last_updated: "2026-05-17T19:16:41.576Z"
---

## Usage

Use the auto-imported `useBreadcrumbItems` composable to generate an automatic breadcrumb list that helps users to navigate between pages.

- Integrates with [Nuxt Schema.org](/docs/schema-org/getting-started/installation) to generate [BreadcrumbList](https://schema.org/BreadcrumbList) structured data.
- Integrates with [Nuxt I18n](https://i18n.nuxtjs.org/) to generate localized breadcrumbs.

## Demo

<code-group>
<breadcrumb-nuxt-ui-example label="Nuxt UI">



</breadcrumb-nuxt-ui-example>

<breadcrumb-raw-example label="Headless">



</breadcrumb-raw-example>
</code-group>

## Modifying Breadcrumbs

Because the breadcrumb is generated automatically, you may need to modify the final output.

It's important to do this within the `useBreadcrumbItems` composable options, as it will ensure that the Schema.org is generated correctly.

### Route Meta

If you need to modify the breadcrumb for a specific static route, you can use the `breadcrumb` property of the route meta.

```vue [Page Meta]twoslash
<script lang="ts" setup>
definePageMeta({
  breadcrumb: {
    icon: 'i-heroicons-home',
    ariaLabel: 'Home'
  },
})
</script>
```

### Overrides

When you need more control over the final output, you can use the `overrides` prop. This allows
you to override any part of the breadcrumb.

The property takes an array of either: `BreadcrumbItemProps`, `false` or `undefined`, the array
of overrides is applied in the order they are provided.

When providing `undefined`, nothing will be overridden. When providing `false`, the breadcrumb
will be removed.

For example, if you have the path `/blog/my-post` and you want to override the `my-post` segment, we need
to target the third item in the array.

```tstwoslash
// path: /blog/my-post will generate ['Home', 'Blog', 'My Post']
useBreadcrumbItems({
  overrides: [
    undefined, // Home
    undefined, // Blog
    {
      label: 'My Awesome Post',
      to: '/blog/my-post',
      icon: 'i-heroicons-home'
    }
  ]
})
```

### `append` and `prepend`

If you need to add items to the end or beginning of the breadcrumb, you can use the `append` and `prepend` props.

```tstwoslash
import { useBreadcrumbItems } from '#imports'

useBreadcrumbItems({
  append: [
    {
      label: 'Final Link'
    }
  ]
})
```

### I18n Integration

If you're using the [@nuxtjs/i18n](https://i18n.nuxtjs.org/) module, you can set breadcrumb labels and aria labels using the keys `breadcrumb.items.{routeName}.label` and `breadcrumb.items.{routeName}.ariaLabel`.

Where `routeName` is the generated name of the Vue Router route.

<callout type="warning">

The `icon` field cannot be set via i18n translations. Use `definePageMeta` or `overrides` instead.

</callout>

<code-group>

```ts [en.ts]
export default {
  breadcrumb: {
    items: {
      index: {
        label: 'Home',
        ariaLabel: 'Home'
      }
    }
  }
}
```

```json [en.json]
{
  "breadcrumb": {
    "items": {
      "index": {
        "label": "Home",
        "ariaLabel": "Home"
      }
    }
  }
}
```

</code-group>

### Hierarchical Breadcrumbs

It's common to want to have a breadcrumb in your top-level layout and then have this be completely dynamic
for each page.

While this will work, it gets more complicated once you need to start overriding the breadcrumb list for data that's only available
from a fetch.

Consider a blog example where we want to show something like:

- Blog (`/blog`) -> Dynamic Category (`/blog/dynamic-category`) -> Post title (`/blog/dynamic-category/post-title`)

You would be tempted to insert the breadcrumb in the blog layout. However, this has issues.

```vue [blog.vue]twoslash
<script lang="ts" setup>
import { useBreadcrumbItems } from '#imports'

const items = useBreadcrumbItems({
  rootSegment: '/blog',
  overrides: [
    { label: 'My Cool Blog', }, // Home
    // ❌ We're missing data to render the post title and category
  ]
})
</script>

<template>
  <div>
    <Breadcrumb :items="useBreadcrumbItems()" />
  </div>
</template>
```

Instead, we need to render the breadcrumb list as late as possible in the render tree. This means we need to
insert the breadcrumb in the page component.

However, this means we may need to do prop drilling to get the data to the breadcrumb. Instead, we can use the shared
breadcrumb context that's based on the `id`.

<code-group>

```vue [app.vue]
<script lang="ts" setup>
// setup root breadcrumb config
useBreadcrumbItems({
  overrides: [
    { label: 'My Cool Site', },
  ]
})
</script>
```

```vue [layouts/blog.vue]twoslash
<script lang="ts" setup>
// example path /blog/<category>/<post>
const category = await useFetch<{ slug: string }>('/api/category', { params: { category: useRoute().params.category } })

// setup breadcrumb root config
useBreadcrumbItems({
  overrides: [
    undefined,
    { label: 'Category', to: `/blog/${category.value.slug}` },
  ]
})
</script>

<template>
  <div>
  <!-- ❌  don't render breadcrumbs here -->
  </div>
</template>
```

```vue [blog/[category]/[...post].vue]
<script lang="ts" setup>
definePageMeta({
  layout: 'blog',
})
// example
const post = await useFetch('/api/post', { params: { post: useRoute().params.post } })

const items = useBreadcrumbItems({
  overrides: [
    undefined, // avoid overriding the root
    undefined,
    { label: 'Post Title', to: `/blog/${useRoute().params.category}/${post.value.slug}` }
  ]
})
</script>

<template>
  <div>
  <!-- ✅ render breadcrumbs here -->
  </div>
</template>
```

</code-group>

This may change your design a bit, but it's the only way to reliable handle this without a hydration issue.

## Props

### `path`

- Type: `MaybeRefOrGetter<string>`
- Default: `useRoute().path`

The path to generate the breadcrumb for.

### `schemaOrg`

- Type: `boolean`
- Default: `true`

Whether to generate [BreadcrumbList](https://schema.org/BreadcrumbList) structured data.

### `ariaLabel`

- Type: `string`
- Default: `'Breadcrumbs'`

The Aria Label for the breadcrumbs.

### `hideRoot`

- Type: `MaybeRefOrGetter<boolean>`
- Default: `false`

Whether the root breadcrumb should be shown.

### `hideCurrent`

- Type: `MaybeRefOrGetter<boolean>`
- Default: `false`

Whether the current breadcrumb should be shown. This is usually the last item in the breadcrumb, but not always.

### `overrides`

- Type: `MaybeRefOrGetter<(BreadcrumbItemProps | false | undefined)[]>`
- Default: `[]`

An array of items to override the generated breadcrumbs with.

### `append`

- Type: `MaybeRefOrGetter<BreadcrumbItemProps[]>`
- Default: `[]`

An array of items to append to the generated breadcrumbs.

### `prepend`

- Type: `MaybeRefOrGetter<BreadcrumbItemProps[]>`
- Default: `[]`

An array of items to prepend to the generated breadcrumbs.

### `rootSegment`

- Type: `string`
- Default: `undefined`

The root segment to use for the breadcrumb. This is useful for when you want to generate a breadcrumb for a specific route.

The default will either use `/` or the i18n prefixed alternative.

### `hideNonExisting`

- Type: `MaybeRefOrGetter<boolean>`
- Default: `false`

Should breadcrumb items with non-existing path be shown.

By default, every path segments will be present in breadcrumb list even if there is no corresponding page for such segment.

<callout icon="i-heroicons-light-bulb">

**Key Integration:** The `useBreadcrumbItems()` composable automatically generates Schema.org BreadcrumbList markup when paired with the [Nuxt Schema.org](/docs/schema-org/getting-started/introduction) module.

</callout>