---
title: "useBreadcrumbItems() · Nuxt SEO Utils · Nuxt SEO"
canonical_url: "https://nuxtseo.com/docs/seo-utils/api/breadcrumbs"
last_updated: "2026-08-15T17:51:00.108Z"
meta:
  description: "A composable used to display a breadcrumb list that helps users to navigate between pages."
  "og:description": "A composable used to display a breadcrumb list that helps users to navigate between pages."
  "og:title": "useBreadcrumbItems() · Nuxt SEO Utils · Nuxt SEO"
---

Nuxt SEO on GitHub

Switch to SEO UtilsSwitch to Nuxt SEOSwitch to RobotsSwitch to SitemapSwitch to OG ImageSwitch to Schema.orgSwitch to Link CheckerSwitch to Site ConfigSwitch to Skew ProtectionSwitch to AI Ready

**Nuxt API**

# **useBreadcrumbItems()**

## 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~~**](https://nuxtseo.com/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

This demo integrates directly with the [Nuxt UI Breadcrumb](https://ui.nuxt.com/navigation/breadcrumb) component.

Enter any path and watch the breadcrumbs be generated!

**Hide Root**

**Hide Current**

```
<script lang="ts" setup>
const items = useBreadcrumbItems() // uses the current route
</script>

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

## 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~~**](http://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
<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.

```ts
// 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.

```ts
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.

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

```ts
export default {
  breadcrumb: {
    items: {
      index: {
        label: 'Home',
        ariaLabel: 'Home'
      }
    }
  }
}
```

### 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
<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**`.

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

This may change your design a bit, but it's the only way to reliably 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 a non-existing path be shown.

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

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

**Was this page helpful?**

### **Related **

[**I18n & Localization**](https://nuxtseo.com/docs/seo-utils/guides/i18n)

[**Nuxt Schema.org**](https://nuxtseo.com/docs/schema-org/getting-started/introduction)

[**Nuxt Site Config**](https://nuxtseo.com/docs/site-config/getting-started/introduction)

[**Config** Configuration options for Nuxt SEO Utils module.](https://nuxtseo.com/docs/seo-utils/api/config) [**useFallbackTitle()** A composable that returns a computed ref with the fallback title for the current page.](https://nuxtseo.com/docs/seo-utils/api/fallback-title)