useBreadcrumbItems()
- Nuxt Redirects
- Nuxt Google Search Console
- Nuxt Internal Links
- Nuxt SEO Analyze
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 to generate BreadcrumbList structured data.
- Integrates with Nuxt I18n to generate localized breadcrumbs.
Demo
This demo integrates directly with the Nuxt UI Breadcrumb component.
<script lang="ts" setup>
const links = useBreadcrumbItems() // uses the current route
</script>
<template>
<UBreadcrumb :links="links"/>
</template>
<script lang="ts" setup>
const links = useBreadcrumbItems() // uses the current route
</script>
<template>
<nav aria-label="Breadcrumbs">
<ul>
<li v-for="(item, key) in links" :key="key">
<NuxtLink v-bind="item">
{{ item.label }}
</NuxtLink>
</li>
</ul>
</nav>
</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 defineBreadcrumbItems
function, 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.
<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: BreadcrumbItem
, 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
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
If you're using the @nuxtjs/i18n module, you can use the key breadcrumbs.items.${routeName}
.
Where routeName
is the generated name of the Vue Router route.
export default {
breadcrumb: {
items: {
index: {
icon: 'i-heroicons-home',
ariaLabel: 'Home'
}
}
}
}
{
"breadcrumb": {
"items": {
"index": {
"icon": "i-heroicons-home",
"ariaLabel": "Home"
}
}
}
}
Props
path
- Type:
string
- Default:
getRoute().path
The path to generate the breadcrumb for.
schemaOrg
- Type:
boolean
- Default:
false
Whether to generate 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:
(BreadcrumbItem | false | undefined)[]
- Default:
[]
An array of items to override the generated breadcrumbs with.
append
- Type:
BreadcrumbItem[]
- Default:
[]
An array of items to append to the generated breadcrumbs.
prepend
- Type:
BreadcrumbItem[]
- Default:
[]
An array of items to prepend to the generated breadcrumbs.