This is a Vue wrapper for the Shepherd, site tour, library.
npm install vue-shepherd shepherd.jsInstall shepherd.js alongside vue-shepherd so you can import its stylesheet (pnpm and Yarn PnP
only let you import packages you depend on directly).
vue-shepherd works with Vue 3 and Nuxt, and is written in TypeScript. Every Shepherd type
(Tour, TourOptions, StepOptions, and so on) is re-exported from vue-shepherd.
Import Shepherd's styles once, in your main.ts:
import 'shepherd.js/dist/css/shepherd.css';<script setup>
import { onBeforeUnmount, onMounted, ref } from 'vue';
import { useShepherd } from 'vue-shepherd';
const el = ref(null);
const tour = useShepherd({
useModalOverlay: true
});
onMounted(() => {
tour.addStep({
attachTo: { element: el.value, on: 'top' },
buttons: [{ action: 'next', text: 'Next' }],
text: 'Test'
});
tour.start();
});
// The steps point at this component's elements, so end the tour with it.
onBeforeUnmount(() => {
if (tour.isActive()) {
tour.cancel();
}
});
</script>
<template>
<div ref="el">Testing</div>
</template>useShepherd(options) returns a new Shepherd Tour. Everything
else, such as steps, buttons, events, and the modal overlay, is Shepherd's own API.
Install the plugin to add this.$shepherd to every component:
import { createApp } from 'vue';
import VueShepherdPlugin from 'vue-shepherd';
import 'shepherd.js/dist/css/shepherd.css';
import App from './App.vue';
createApp(App).use(VueShepherdPlugin).mount('#app');<script>
export default {
data() {
return { tour: null };
},
mounted() {
this.tour = this.$shepherd({ useModalOverlay: true });
this.tour.addStep({
attachTo: { element: this.$refs.el, on: 'top' },
text: 'Test'
});
this.tour.start();
},
beforeUnmount() {
this.tour?.cancel();
}
};
</script>
<template>
<div ref="el">Testing</div>
</template>No module is needed. Add the styles in nuxt.config.ts:
export default defineNuxtConfig({
css: ['shepherd.js/dist/css/shepherd.css']
});useShepherd works as shown above. It is safe during server rendering: on the server, Shepherd
returns a tour whose methods do nothing, and the real tour is created when the component runs in
the browser. Start tours in onMounted, which only runs in the browser.
For this.$shepherd, register the plugin in plugins/shepherd.ts:
import VueShepherdPlugin from 'vue-shepherd';
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(VueShepherdPlugin);
});dist/vue-shepherd.min.js includes Shepherd and exposes a VueShepherd global, for use with
Vue's global build:
<link rel="stylesheet" href="https://unpkg.com/shepherd.js/dist/css/shepherd.css" />
<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/vue-shepherd"></script>
<script>
const { useShepherd } = VueShepherd;
Vue.createApp(App).use(VueShepherd.default).mount('#app');
</script>Callbacks such as beforeShowPromise, showOn, and button actions are plain functions, so they
can use anything in the scope where the tour is created. In <script setup>, that includes your
refs, stores, and router:
const router = useRouter();
const { refetch } = useQuery(PROJECTS);
tour.addStep({
attachTo: { element: '#projects', on: 'bottom' },
beforeShowPromise: async () => {
await router.push('/projects');
await refetch();
},
text: 'Your projects'
});To keep steps in their own file, export a function that takes what the steps need and returns
them, then call it from your component: tour.addSteps(createSteps({ router, refetch })). In the
Options API, use arrow functions so this stays the component.
Tour events, such as complete and cancel, are on the tour, not on its steps:
tour.on('complete', () => saveTourSeen());
tour.on('cancel', () => saveTourSeen());Step events (show, hide, and so on) go in each step's when option.
Shepherd ships a counter and progress bar:
import 'shepherd.js/dist/css/theme.css';
import { stepProgress } from 'shepherd.js/motion';
const stop = stepProgress(tour);text accepts an element, so you can render a component into one and unmount it when the step is
destroyed:
import { h, render } from 'vue';
import StepContent from './StepContent.vue';
const container = document.createElement('div');
tour.addStep({
text: () => {
render(h(StepContent, { name: 'Vue' }), container);
return container;
},
when: {
destroy: () => render(null, container)
}
});A component rendered this way is outside your app, so it can't use plugins such as the router or
Pinia, or inject. Pass what it needs as props.
vue-shepherd is licensed under AGPL-3.0 (for open source and non-commercial use) with a Commercial License available for commercial use.
- Free for open source and non-commercial projects under AGPL-3.0
- Commercial license required for commercial products and revenue-generating companies
