// Tutorial //

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

Published on March 20, 2018
Default avatar
By Joshua Bemenderfer
Developer and author at DigitalOcean.
Guide Users Through Your Vue.js App with vue-tour

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

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…

main.js
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:

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


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!