Guide Users Through Your Vue.js App with vue-tour

Developing web apps is hard. There are so many things to think about. Way, way, waaay too many. It’s easy to get caught up in the details and forget one important little thing: How will users know how to use your app once it’s done? The simplest way is to add a little tour-guide component that pops up and explains each step. Except those are kind of difficult to implement yourself. Thankfully, if you’re using Vue.js, vue-tour has you covered. It’s a super-simple library that makes writing tour guides about as simple as could be.

Dependencies

If you don’t have a project set up already, go ahead and start one using vue-cli 3.0 beta and the default options. $ vue create my-new-project and hitting enter a couple times should be sufficient.

Then, you’ll want to install vue-tour from npm:

$ npm install vue-tour

# or with Yarn:
$ yarn add vue-tour

Set Up

Enable the plugin and load the CSS…

import Vue from 'vue';
import App from './App.vue';
import VueTour from 'vue-tour';
// You could use your own fancy-schmancy custom styles.
// We'll use the defaults here because we're lazy.
import 'vue-tour/dist/vue-tour.css';

Vue.use(VueTour);

new Vue({
  el: '#app',
  render: h => h(App)
});

Usage

Now that all the formalities are out of the way, here’s a four-step guide as to how vue-tour works.

• Step 1. Add unique classes or properties to whichever elements you want your tour steps to target.
• Step 2. Define your steps as an array of objects in your component’s data property (or anywhere else), each containing a target property that is a CSS selector for the relevant element you modified above. Add a content property next to target that contains the text you want that step to have.
• Step 3. Add a <vue-tour name="whateverMyTourNameIs" :steps="mySteps"></vue-tour> component somewhere in your app.
• Step 4. Run this.$tours['whateverMyTourNameIs'].start() in your mounted hook, or whenever you want the tour to start.

Done! Was that a little fast for you? Here’s the guide again in code form:

<template>
  <div id="app">
    <!-- Note the data-tour-step property hiding in plain sight. -->
    <button data-tour-step="1">Complicated Button</button>
    <a data-tour-step="2" href="https://alligator.io">Confounding Link</a>
    <h1 data-tour-step="3">Perplexing Header Element</h1>
    <p>Self describing paragraph. It needs no tour step. Really.</p>

    <!-- The helpful tour guide that will make all things clear. -->
    <vue-tour name="explanatoryTour" :steps="steps"></vue-tour>
  </div>
</template>

<script>
export default {
  data () {
    return {
      steps: [
        {
          // I prefer using data attributes, but you can use
          // classes, ids, or whatever else you want!
          // (So long as document.querySelector() likes it.)
          target: '[data-tour-step="1"]',
          content: `This button doesn't actually do anything.`
        },
        {
          target: '[data-tour-step="2"]',
          // You can even use HTML!
          content: `This link will take you to <a href="https://alligator.io">https://alligator.io</a>!`
        },
        {
          target: '[data-tour-step="3"]',
          content: `This is a header element. It's big. Not much else to say about it.`,
          params: {
            // You can control the position of the tour popup easily.
            placement: 'bottom'
          }
        }
      ]
    }
  },

  mounted () {
    // TODO: Hide me after the first visit so returning users don't get annoyed!
    this.$tours['explanatoryTour'].start();
  }
}
</script>

Oh, and if you want to modify the popup template, you can do that too.

So do your users (and yourself!) a favor. Use vue-tour to make clear the usage of the great and wonderful app you have conjured up.