Skip to content

About

A Vue wrapper for the site tour library Shepherd

Resources

Stars

340 stars

Watchers

3 watching

Forks

Repository files navigation

vue-shepherd

Ship Shape

vue-shepherd is built and maintained by Ship Shape. Contact us for web app consulting, development, and training for your project.

npm version Download count all time npm CI Build

This is a Vue wrapper for the Shepherd, site tour, library.

npm install vue-shepherd shepherd.js

Install 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.

Usage

Import Shepherd's styles once, in your main.ts:

import 'shepherd.js/dist/css/shepherd.css';

Composition API (suggested)

<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.

Options 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>

Nuxt

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);
});

Script tag

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>

Recipes

Use component state in step callbacks

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.

Listen to tour events

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.

Show progress

Shepherd ships a counter and progress bar:

import 'shepherd.js/dist/css/theme.css';
import { stepProgress } from 'shepherd.js/motion';

const stop = stepProgress(tour);

Render a Vue component in a step

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.

License

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

📄 Read License Details
💳 Purchase Commercial License

About

A Vue wrapper for the site tour library Shepherd

Resources

Stars

340 stars

Watchers

3 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages