Skip to content

OSSPhilippines/vue-footprints

Repository files navigation

Vue Footprints 👣

Breadcrumbs plugin for Vue.js & Vue Router. Why footprints? Coz it's similar to the idea of breadcrumbs. Also, there's already a bunch of packages that has "breadcrumbs" on their name.

NOTE: This requires Vue Router to work.

Is this compatible with Vue 2? I don't know, I haven't tried. It might tho, give it a try.

Installation

Yarn

yarn add @ossph/vue-footprints

NPM

npm install @ossph/vue-footprints

Usage

Mixin

This will add a global computed mixin array called $footprints. Remember this one, we'll talk about it in the implmentation part.

import { createApp } from 'vue'
import { VueFootprintsMixin } from '@ossph/vue-footprints';

const app = createApp({});

app.use(VueFootprintsMixin, { returnRoute: true });

Composable

You can also create a local implementation using the composable version.

import { useRoute } from 'vue-router';

export default {
  setup () {
    const route = useRoute();
    const { footprints } = useFootprints(route, { returnRoute: true });
    // footprints.value yields an array of route footprints
  },
};

Options

Both the mixin installation and the composable have the same options parameters.

Option Type Default Description
returnRoute Boolean false If true, the route object will be returned in the footprints array.

Implementation with Vue App

Step 1

In your Vue Router routes, add the object footprint in the meta object of each route that you want to be added to the footprints. Assumming that you have the routes below:

|- grandparent
  |- parent
    |- child 1
    |- child 2
...
{
  path: '/grandparent',
  name: 'grandparent',
  meta: {
+    footprint: {
+      name: 'Grandparent',
+    },
  },
  component: () => import('pages/GrandParentPage'),
  children: [
    {
      path: 'parent',
      name: 'parent',
      component: () => import('pages/ParentPage'),
      meta: {
+        footprint: {
+          name: 'Parent',
+        },
      },
      children: [
        {
          path: 'child-1',
          name: 'child-1',
          component: () => import('pages/ChildOnePage'),
          meta: {
+            footprint: {
+              name: 'Child 1',
+            },
          },
        },
        {
          path: 'child-2',
          name: 'child-2',
          component: () => import('pages/ChildTwoPage'),
          meta: {
+            footprint: {
+              name: 'Child 2',
+            },
          },
        },
      ],
    },
  ],
}

Step 2

Given the input above, the $footprints will look like this depending on how deep you are in the route history. Say you're just in the /grandparent it will look like:

$footprints: [
  {
    footprint: {
      name: 'Grandparent'
    },
    active: true,
    route: {
      name: 'grandparent',
      path: '/grandparent'
    }
  }
]

But if you're in the /grandparent/parent it will look like:

$footprints: [
  {
    footprint: {
      name: 'Grandparent'
    },
    active: false,
    route: {
      name: 'grandparent',
      path: '/grandparent'
    }
  },
  {
    footprint: {
      name: 'Parent'
    },
    active: true,
    route: {
      name: 'parent',
      path: '/grandparent/parent'
    }
  }
]

And finally if you're in /granparent/parent/child-1 it will look like:

$footprints: [
  {
    footprint: {
      name: 'Grandparent'
    },
    active: false,
    route: {
      name: 'grandparent',
      path: '/grandparent'
    }
  },
  {
    footprint: {
      name: 'Parent'
    },
    active: false,
    route: {
      name: 'parent',
      path: '/grandparent/parent'
    }
  },
  {
    footprint: {
      name: 'Child 1'
    },
    active: true,
    route: {
      name: 'child-1',
      path: '/grandparent/parent/child-1'
    }
  }
]

Step 3

Do whatever you want with the $footprints object. In my case I made this for my quasar app so I used their QBreadcrumbs component.

API (Object structure)

$footprints: [
  {
    // Whatever you put Route#meta.footer will appear here
    footprint: Object,
    // True if the this footprint is the active route. False, otherwise.
    active: Boolean,
    // The route object in case you want to use it.
    // You can return everything or just the essential by
    // passing returnRoute: true in the options. 
    // E.x. app.use(VueFootprints, { returnRoute: true });
    route: Object,
  }
]

Example

This is just a screenshot from my app, I don't have time create an example, sorry. If you have a question, join our discord server.