Nuxt Crumbs 🍞

Effortless, SSR-ready breadcrumbs for your Nuxt app.

A unified way to manage breadcrumbs in your Nuxt app. Define each breadcrumb on the page where its data lives, then render the full trail anywhere you like, even from a Nuxt layout! Labels can be static or derived from data fetched on the page, with full SSR support.

Features

• 🗺️  breadcrumbs generated automatically from your route hierarchy
• ⚡️  set crumb labels from fetched data with defineBreadcrumbs
• 🎨  fully customizable: bring your own markup and styling
• 🪶  lightweight and performant
• 🌐  SSR-safe out of the box
• 💪  fully typed, with support for augmentation

🚀 Usage

Install

1. Install the module to your project:

npm install nuxt-crumbs

2. Add it to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    'nuxt-crumbs',
  ],
})

Add a crumb to a page

The simplest way to give a page a breadcrumb is through definePageMeta. Each matched route that declares a breadcrumb becomes a segment in the trail, in hierarchy order.

<!-- pages/about.vue -->
<script setup lang="ts">
definePageMeta({
  breadcrumb: 'About',
})
</script>

Visiting /about now yields a trail of: About. Nested routes stack automatically, so pages/blog/[slug].vue under pages/blog.vue produces Blog › Post title.

Dynamic crumbs

When a label isn't known ahead of time, for example when it depends on fetched data, reach for the defineBreadcrumbs compiler macro. SSR waits for it to settle before rendering the breadcrumbs component.

<!-- pages/blog/[slug].vue -->
<script setup lang="ts">
const route = useRoute()
// we await useAsyncData 👇
const { data: post } = await useAsyncData(() => fetchPost(route.params.slug))

// `post` is now available at this point,
// we can snapshot its title into the leaf breadcrumb
defineBreadcrumbs({
  label: post.value.title
})
</script>

Passing an object sets the crumb for the current page (the leaf of the trail). For more control, pass a callback instead. It receives a context object holding the breadcrumbs already resolved from the route hierarchy, and the returned array becomes the new trail. This is handy when a crumb further up the trail also depends on fetched data.

defineBreadcrumbs(({ crumbs }) => {
  return [
    ...crumbs.map((crumb) => {
      // use the category name from fetched data
      if (crumb.routeName === 'category-slug') {
        return { ...crumb, label: product.value.category.name }
      }
      return crumb
    }),
    // append the leaf crumb
    { label: product.value.name },
  ]
})

Rendering the trail

Use the <NuxtCrumbs> component to access the trail. It exposes the resolved crumbs array through its default slot, so you can bring your own markup and styling:

<template>
  <nav aria-label="Breadcrumb">
    <ul>
      <NuxtCrumbs v-slot="{ crumbs }">
        <li v-for="(crumb, index) in crumbs" :key="crumb.label">
          <span v-if="index" aria-hidden="true">›</span>
          <NuxtLink :to="crumb.to">{{ crumb.label }}</NuxtLink>
        </li>
      </NuxtCrumbs>
    </ul>
  </nav>
</template>

The slot receives:

| Slot prop | Type | Description | | --------- | ---------------------- | ------------------------------------ | | crumbs | BreadcrumbResolved[] | The resolved breadcrumb trail. |

Each crumb is a resolved breadcrumb:

| Property | Type | Description | | ----------- | -------------------------- | ----------------------------------------------- | | label | string | The text to display. | | to | RouteLocationRaw | A route location ready to pass to <NuxtLink>. | | routeName | string \| symbol \| null | The name of the route the crumb points to. |

Custom crumb data

Sometimes a label isn't enough, you also want an icon, or some other flag to travel with each crumb. Augment the Breadcrumb interface through the #crumbs module and your extra fields flow through the whole pipeline, fully typed: from where you define them all the way to the render slot.

// index.d.ts
declare module '#crumbs' {
  interface Breadcrumb {
    icon?: string
  }
}

export {}

Set the extra data wherever you define a crumb, both definePageMeta and defineBreadcrumbs accept it:

<script setup lang="ts">
definePageMeta({
  breadcrumb: { label: 'About', icon: 'i-lucide-info' },
})

// or from the macro
defineBreadcrumbs({ label: post.value.title, icon: 'i-lucide-file' })
</script>

🧑‍💻 Contributing

• Clone this repository
• Install dependencies using pnpm install
• Run pnpm dev:prepare to generate type stubs
• Use pnpm dev to start the playground in development mode

📑 License

Published under the MIT License.