vue-3-breadcrumbs v2.0.0

Breadcrumbs

Description

This plugin adds breadcrumbs to your project based on vue 3 or nuxt 3. It provides easy and variable setup with Vue Router. Also, it includes the small component.

Dependencies

• Vue 3
• Vue Router

Installation

npm i vue-3-breadcrumbs

Usage

Inclusion

import { createApp } from 'vue'
import App from './App.vue'
import breadcrumbs from 'vue-3-breadcrumbs'

const app = createApp(App)

app.use(breadcrumbs, {
    includeComponent: false // {boolean} [includeComponent=false] - Include global breadcrumbs component or not
})

Usage description

// Every breadcrumb is an object:
$breadcrumbs[0] = {
    label: "My first crumb", // {String} label - text of a crumb
    link: '/some-path#special', // {String} [link=route.path] - crumb's "to" attribute for <router-link> component
    current: false, // {Boolean} current - whether the breadcrumb relates to the current route or not. Usually current crumb is last one, except cases when it has falsy value.
    _path: '/some_path', // {String} path - part of the current route.path related to crumb. Used as crumb's identifier
}

Breadcrumbs will be recalculated on every Vue Router afterEach hook.
If breadcrumb already exist in current chain, it won't be recalculated.

export default {
    name: 'catalogPage',
    mounted() {
        console.log(this.$breadcrumbs.value) // you can simply get current breadcrumbs
        
        // You can reactively change it
        // !! It won't change meta object, or object returned by breadcrumb function
        this.$breadcrumbs.value[0].label = 'New label'
        
        // if for some reason you need to recalculate breadcrumbs or create crumb for some path u can use these methods
        /**
         * Recalculate breadcrumbs for route
         * @param {object} route
         */
        $breadcrumbs.setBreadcrumbsByRoute(this.$route)
        /**
         * Create breadcrumb object by path
         * @param {string} path  
         * @param {boolean} [isCurrent = false]
         */
        const newCrumb = $breadcrumbs.createBreadcrumb('/some-path', true)
    }
}

If you want to access breadcrumbs in Composition API (setup option), read this docs

Router settings

const routes = [
    {
        path: '/', // default link for crumb
        component: Home,
        meta: {
            breadcrumb: 'Home' // Can be just a string
        },
    },
    {
        path: '/about',
        component: About,
        meta: {
            // Can be an object
            breadcrumb: {
                label: 'About Crumb',
                link: '/about#special' // custom link
            },
        }
    },
    {
        path: '/catalog',
        component: Catalog,
        meta: {
            breadcrumb: false // If crumb has falsy value, it would be skipped
        },
    },
    {
        path: '/catalog/:id',
        component: Item,
        meta: {
            /**
             * Can be a function that returns string, object or falsy value (see above)
             * @param {object} route - crumbs's route
             * @param {object} app - object resulting from Vue's createApp
             */
            breadcrumb (route, app) {
                return `Item ${route.params.id}` 
            },
        },
        children: [
            {
                path: '/catalog/:id/:sub',
                component: SubItem,
                meta: {
                    breadcrumb(route, app) {
                        // Using api
                        let breadcrumb = app.config.globalProperties.$api.getBreadcrumb(route)
                        return {
                            label: `SubItem ${breadcrumb}`,
                            link: `${route.path}#special`
                        }
                    },
                },
            },
        ],
    },
]

const router = createRouter({
    routes,
})

Component usage

Don't forget to include it first (by includeComponent option). This is async component, so it won't be imported, if you don't use it

<AmBreadcrumbs
    :showCurrentCrumb="true" <!-- {Boolean} [showCurrentCrumb=true] - Whether to show the breadcrumb of current route or not -->
/>

//or 
<AmBreadcrumbs>
    <template #crumb="{ crumb }">
        <router-link
            class="my-custom-crumb"
            :to="crumb.link"
        >
            {{ crumb.label }}
        </router-link>
    </template>
</AmBreadcrumbs>

Nuxt

Works within ssr mode 1. Add plugin

// plugins/breadcrumbs.js
import { defineNuxtPlugin } from '#app'
import breadcrumbs from 'vue-3-breadcrumbs'

export default defineNuxtPlugin((nuxtApp) => {
    const app = nuxtApp.vueApp.use(breadcrumbs, {
        includeComponent: true, // same as for vue
    })

    // without this return, you won't be able to access $breadcrumbs from useNuxtApp directly,
    // but this.$breadcrumbs will be available anyway
    return {
        provide: {
            breadcrumbs: app.config.globalProperties.$breadcrumbs
        }
    }
})

2. Set breadcrumbs for pages

// pages/index.vue
export default {
    name: 'mainPage',
    setup() {
        definePageMeta({
            breadcrumb: 'Home page' // string, object or function
        })
    },
}

3. Use Component (see vue above)

<AmBreadcrumbs/>

4. Access breadcrumbs

// pages/index.vue
export default {
    name: 'mainPage',
    setup() {
        const { $breadcrumbs } = useNuxtApp()
        console.log('Breadcrumbs array', $breadcrumbs.value)
    },
    mounted() {
        console.log('Breadcrumbs in mounted', this.$breadcrumbs.value)
    },
}