useBreadcrumbItems() · Nuxt SEO Utils · Nuxt SEO

[NuxtSEO](https://nuxtseo.com/ "Home")

- [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Tools](https://nuxtseo.com/tools)
- [Pro](https://nuxtseo.com/pro)
- [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases)

[1.4K](https://github.com/harlan-zw/nuxt-seo)

[Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo)

[User Guides](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)

[API](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs)

[Releases](https://nuxtseo.com/docs/seo-utils/releases/v8)

SEO Utils

- [Switch to SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Switch to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Switch to Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Switch to Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [Switch to OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Switch to Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Switch to Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [Switch to Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Switch to Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [Switch to AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

Search…```k`` /`

v8.1.7

- Playgrounds
- [Discord Support](https://discord.com/invite/275MBUBvgP)

### Nuxt API

- [`useBreadcrumbItems()`](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs)
- [`useFallbackTitle()`](https://nuxtseo.com/docs/seo-utils/api/fallback-title)
- [`useShareLinks()`](https://nuxtseo.com/docs/seo-utils/api/share-links)
- [nuxt.config.ts](https://nuxtseo.com/docs/seo-utils/api/config)

Nuxt API

# useBreadcrumbItems()

[Copy for LLMs](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs.md)

## [Usage](#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](#demo)

Nuxt UI

Headless

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

1. [Home](https://nuxtseo.com/)
2.
3. [Docs](https://nuxtseo.com/docs)
4.
5. [Seo Utils](https://nuxtseo.com/docs/seo-utils)
6.
7. [Api](https://nuxtseo.com/docs/seo-utils/api)
8.
9. [Breadcrumbs](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs)

Enter any path and watch the breadcrumbs be generated!

Hide Root

Hide Current

components/Breadcrumbs.vue

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

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

- [Home](https://nuxtseo.com/)
- [Docs](https://nuxtseo.com/docs)
- [Seo Utils](https://nuxtseo.com/docs/seo-utils)
- [Api](https://nuxtseo.com/docs/seo-utils/api)
- [Breadcrumbs](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs)

Enter any path and watch the breadcrumbs be generated!

Hide Root

Hide Current

components/Breadcrumbs.vue

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

<template>
<nav aria-label="Breadcrumbs">
  <ul>
    <li v-for="(item, key) in items" :key="key">
      <NuxtLink v-bind="item">
        {{ item.label }}
      </NuxtLink>
    </li>
  </ul>
</nav>
</template>
```

## [Modifying Breadcrumbs](#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](#route-meta)

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

Page Meta

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

### [Overrides](#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.

```
// 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`](#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.

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

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

### [I18n Integration](#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.

en.ts

en.json

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

```
{
  "breadcrumb": {
    "items": {
      "index": {
        "label": "Home",
        "ariaLabel": "Home"
      }
    }
  }
}
```

### [Hierarchical Breadcrumbs](#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.

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

app.vue

layouts/blog.vue

blog/[category]/[...post].vue

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

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

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

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

## [Props](#props)

### [`path`](#path)

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

The path to generate the breadcrumb for.

### [`schemaOrg`](#schemaorg)

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

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

### [`ariaLabel`](#arialabel)

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

The Aria Label for the breadcrumbs.

### [`hideRoot`](#hideroot)

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

Whether the root breadcrumb should be shown.

### [`hideCurrent`](#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`](#overrides-1)

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

An array of items to override the generated breadcrumbs with.

### [`append`](#append)

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

An array of items to append to the generated breadcrumbs.

### [`prepend`](#prepend)

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

An array of items to prepend to the generated breadcrumbs.

### [`rootSegment`](#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`](#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.

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

[Edit this page](https://github.com/harlan-zw/nuxt-seo-utils/edit/main/docs/content/3.api/4.breadcrumbs.md)

[Markdown For LLMs](https://nuxtseo.com/docs/seo-utils/api/breadcrumbs.md)

Did this page help you?

[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)

On this page

- [Usage](#usage)
- [Demo](#demo)
- [Modifying Breadcrumbs](#modifying-breadcrumbs)
- [Props](#props)

[GitHub](https://github.com/harlan-zw/nuxt-seo) [ Discord](https://discord.com/invite/275MBUBvgP)

### [NuxtSEO](https://nuxtseo.com/ "Home")

- [Getting Started](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [MCP](https://nuxtseo.com/docs/nuxt-seo/guides/mcp)

Modules

- [Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

### [NuxtSEO Pro](https://nuxtseo.com/pro "Home")

- [Getting Started](https://nuxtseo.com/pro)
- [Dashboard](https://nuxtseo.com/pro/dashboard)
- [Pro MCP](https://nuxtseo.com/docs/nuxt-seo-pro/mcp/installation)

### [Learn SEO](https://nuxtseo.com/learn-seo "Learn SEO")

Nuxt

- [Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers)
- [Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen)
- [Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
- [Staying Secure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security)

Vue

- [Vue SEO Guide](https://nuxtseo.com/learn-seo/vue)
- [Mastering Meta](https://nuxtseo.com/learn-seo/vue/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/vue/controlling-crawlers)
- [SPA SEO](https://nuxtseo.com/learn-seo/vue/spa)
- [SSR Frameworks](https://nuxtseo.com/learn-seo/vue/ssr-frameworks)
- [SEO Checklist](https://nuxtseo.com/learn-seo/checklist)
- [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup)
- [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks)

### [Tools](https://nuxtseo.com/tools "SEO Tools")

- [Social Share Debugger](https://nuxtseo.com/tools/social-share-debugger)
- [Robots.txt Generator](https://nuxtseo.com/tools/robots-txt-generator)
- [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker)
- [HTML to Markdown](https://nuxtseo.com/tools/html-to-markdown)
- [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator)
- [Schema.org Validator](https://nuxtseo.com/tools/schema-validator)
- [Keyword Idea Generator](https://nuxtseo.com/tools/keyword-generator)
- [Keyword Research](https://nuxtseo.com/tools/keyword-research)
- [SERP Analyzer](https://nuxtseo.com/tools/serp-analyzer)
- [Domain Rankings](https://nuxtseo.com/tools/domain-rankings)

Copyright © 2023-2026 Harlan Wilton - [MIT License](https://github.com/harlan-zw/nuxt-seo/blob/main/license) · [mdream](https://mdream.dev)