sgx-nuxt-breadcrumbs v2.0.6

sgx-nuxt-breadcrumbs

Breadcrumbs feature for Nuxt.

Setup

1. Install package:

npm install sgx-nuxt-breadcrumbs

2. Add package to modules in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['sgx-nuxt-breadcrumbs']
})

3. Add <SgxBreadcrumbs> component to layout or app.vue:

<template>
  <div>
    <SgxBreadcrumbs />
    <NuxtPage />
  </div>
</template>

Configuration

Types:

interface NuxtConfig {
  sgxBreadcrumbs?: ModuleOptions
}

interface ModuleOptions {
  // Prefix for components and composables
  // Default: 'Sgx'
  prefix?: string

  // Add/remove trailing slash for breadcrumbs links
  // Default: undefined
  trailingSlash?: boolean
}

Usage:

Set module options to sgxBreadcrumbs in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['sgx-nuxt-breadcrumbs'],
  sgxBreadcrumbs: {
    // Module options...
  }
})

Page properties

Type:

interface PageMeta {
  // Base page title
  title?: string

  // Parent page path (add custom parent recursively)
  parent?: string

  // Breadcrumbs link
  breadcrumbsLink?: BreadcrumbsLinkMeta | BreadcrumbsLinkMeta[]

  // Breadcrumbs params
  breadcrumbs?: {
    // Component visibility
    visible?: boolean

    // Custom params
    [key: string]: unknown
  }
}

// Breadcrumbs link params
interface BreadcrumbsLinkMeta {
  // Label
  // Default: Inherit from base page title
  // or generated from last slug if undefined
  label?: string

  // Path
  // Default: From current matched route
  to?: string

  // Disable link (make non-clickable)
  // Default: false
  disabled?: boolean

  // Exclude link
  // Default: false
  excluded?: boolean

  // Exclude previous links
  // Default: false
  previousExcluded?: boolean

  // Custom link params
  [key: string]: unknown
}

Usage:

Auto-label from last URL slug if no params:

<script setup lang="ts">
definePageMeta({
  // Empty...
})
</script>

Breadcrumbs label from base page title:

<script setup lang="ts">
definePageMeta({
  title: 'List of posts'
})
</script>

Override base page title for breadcrumbs link:

<script setup lang="ts">
definePageMeta({
  title: 'List of posts',
  breadcrumbsLink: {
    label: 'Posts'
  }
})
</script>

Set custom path for breadcrumbs link:

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: {
    to: '/my-custom/path'
  }
})
</script>

Add parent page link:

<script setup lang="ts">
// Current page: /posts/post-1
definePageMeta({
  parent: '/categories/category-1'
})
// Breadcrumbs: Home -> Posts -> Category 1 -> Post 1
</script>

Add many custom links before and after:

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: [
    { to: '/page-1', label: 'Page 1' }
    { to: '/page-2', label: 'Page 2' }
    // Current page without 'to'
    { label: 'Current page'}
    { to: '/page-3', label: 'Page 3 after' }
    { to: '/page-4', label: 'Page 4 after' }
  ]
})
// Breadcrumbs: Home -> Page-1 -> Page-2 -> Current page-> Page-3 -> Page-4
</script>

Disable link (make link non-clickable):

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: {
    disabled: true
  }
})
</script>

Exclude link from breadcrumbs:

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: {
    excluded: true
  }
})
</script>

Exclude all previous links from breadcrumbs:

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: {
    previousExcluded: true
  }
})
</script>

Custom params for breadcrumbs link:

<script setup lang="ts">
definePageMeta({
  breadcrumbsLink: {
    myCustomIcon: 'my-custom-icon',
    myCustomParam1: 'my-custom-param-1',
    myCustomParam2: 'my-custom-param-2'
    // Other...
  }
})
</script>

Hide breadcrumbs component:

<script setup lang="ts">
definePageMeta({
  breadcrumbs: {
    visible: false
  }
})
</script>

Custom params for breadcrumbs:

<script setup lang="ts">
definePageMeta({
  breadcrumbs: {
    myCustomParam1: 'my-custom-param-1',
    myCustomParam2: 'my-custom-param-2'
    // Other...
  }
})
</script>

Dynamic params:

<script setup lang="ts">
definePageMeta({
  async middleware(route) {
    const data = await fetchData(route.params)

    // route.meta.title = ...

    // One link
    // route.meta.breadcrumbsLink = {...}

    // Many links
    // route.meta.breadcrumbsLink = [...]
  }
})
</script>

Components

<SgxBreadcrumbs>

Types:

interface BreadcrumbsProps {
  // Element
  // Default: 'div'
  as?: string

  // Enable last link (make clickable)
  // Default: false
  lastLinkEnabled?: boolean
}

interface BreadcrumbsSlot {
  // Breadcrumbs links
  links: BreadcrumbsLink[]

  // Custom params
  [key: string]: unknown
}

interface BreadcrumbsLink {
  // Label
  label: string

  // Path
  to: string

  // Disabled (non-clickable)
  disabled: boolean

  // Active (last link)
  current: boolean

  // Custom params
  [key: string]: unknown
}

Usage:

Basic usage:

<template>
  <SgxBreadcrumbs />
</template>

Override component template:

<template>
  <SgxBreadcrumbs v-slot="{ links, myCustomParam1, myCustomParam2 }">
    <ul>
      <li v-for="(link, index) in links" :key="index">
        <NuxtLink v-if="!link.current" :to="link.to">
          <i>{{ link.myCustomIcon }}</i>
          <span>{{ link.label }}</span>
        </NuxtLink>
        <span v-else>{{ link.label }}</span>
      </li>
    </ul>
    <p>{{ myCustomParam1 }}</p>
    <p>{{ myCustomParam2 }}</p>
  </SgxBreadcrumbs>
</template>

Usage with Nuxt UI Breadcrumbs component:

<template>
  <SgxBreadcrumbs v-slot="{ links }">
    <UBreadcrumb :links="links" />
  </SgxBreadcrumbs>
</template>

Composables

useSgxBreadcrumbs

Type:

interface BreadcrumbsComposable {
  (params?: BreadcrumbsParams): ComputedRef<Breadcrumbs>
}

interface Breadcrumbs {
  // Breadcrumbs links
  links: BreadcrumbsLink[]

  // Component visibility
  visible: boolean

  // Custom params
  [key: string]: unknown
}

interface BreadcrumbsLink {
  // Label
  label: string

  // Path
  to: string

  // Disabled (non-clickable)
  disabled: boolean

  // Active (last link)
  current: boolean

  // Custom params
  [key: string]: unknown
}

interface BreadcrumbsParams {
  // Enable last link
  // Default: false
  lastLinkEnabled?: boolean
}

Usage:

<template>
  <div v-if="breadcrumbs.visible">
    <ul>
      <li v-for="(link, index) in breadcrumbs.links" :key="index">
        <NuxtLink v-if="!link.current" :to="link.to">
          <i>{{ link.myCustomIcon }}</i>
          <span>{{ link.label }}</span>
        </NuxtLink>
        <span v-else>{{ link.label }}</span>
      </li>
    </ul>
    <div>{{ breadcrumbs.myCustomParam1 }}</div>
    <div>{{ breadcrumbs.myCustomParam2 }}</div>
  </div>
</template>

<script setup lang="ts">
const breadcrumbs = useSgxBreadcrumbs()
</script>

Basic example

Pages:

-| blog/
---| index.vue
---| post-1.vue
---| post-2.vue
---| post-3.vue
-| index.vue

Generated breadcrumbs:

• / - Home
• /blog - Home > Blog
• /blog/post-1 - Home > Blog > Post 1
• /blog/post-2 - Home > Blog > Post 2
• /blog/post-3 - Home > Blog > Post 3

Development

# Clone repository
git clone https://github.com/sergenux/sgx-nuxt-breadcrumbs.git

# Change directory
cd sgx-nuxt-breadcrumbs

# Install dependencies
npm install

# Prepare types
npm run dev:prepare

# Develop with playground
npm run dev

# Build playground
npm run dev:build

# Code checks
npm run typecheck
npm run lint
npm run lint:fix
npm run format
npm run format:fix