Vue Tour

2.0.0 · active · verified Sun Apr 19

Vue Tour is a lightweight, simple, and customizable plugin designed to guide users through applications built with Vue.js. It allows developers to create interactive, step-by-step tours by targeting specific DOM elements. The current stable version is 2.0.0, which was released recently and includes a significant update to Popper.js v2.x for positioning. While not on a strict release cadence, the project shows active development with features like sticky steps, promise-based `before` hooks for async operations, and element highlighting introduced in previous minor versions. Its primary differentiator is its simplicity and direct integration with Vue's reactivity system, making it a straightforward choice for adding onboarding or feature discovery flows without heavy dependencies, utilizing standard CSS selectors for targeting tour steps.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'start') OR TypeError: this.$tours[tourName] is undefined
```
cause The tour component (`<v-tour>`) was not rendered, or its `name` prop does not match the key used to call `this.$tours[tourName].start()`.

fix Verify that `<v-tour name="myTour" :steps="steps"></v-tour>` is present in your template and that the `name` prop (e.g., 'myTour') exactly matches the string used to access it via `this.$tours['myTour']`.
```
Popper: `modifiers.popperOffsets.offset` (or similar property) is not a valid Popper.js v2 option.
```
cause This error occurs after upgrading to vue-tour v2.0.0 if you are still passing Popper.js v1.x options in your step `params`.

fix Consult the Popper.js v2.x documentation for the correct syntax and available options. Update the `params` object for each step to conform to the new Popper.js API.
```
Error: [Vue warn]: The client-side rendered virtual DOM tree is not matching server-rendered content. This is likely caused by incorrect HTML markup
```
cause This can occur when using SSR (Server-Side Rendering) if Vue Tour's DOM manipulations or dynamic elements cause a mismatch between the server-rendered and client-side hydrated content.

fix Consider dynamically importing or rendering `<v-tour>` only on the client-side using a `<client-only>` wrapper in Nuxt.js or a similar mechanism in other SSR frameworks, or ensure all tour-related elements are fully mounted before hydration.

Warnings

breaking Vue Tour v2.0.0 updated its internal Popper.js dependency to v2.x. Any custom Popper.js options passed via step parameters must be updated to align with Popper.js v2.x API changes.
Fix: Review the Popper.js v2.x documentation for updated option names and structures. Adjust your `params` object within each tour step accordingly. For example, some 'placement' options might have changed or been reorganized.
gotcha Tour steps rely on `target` selectors (e.g., `#id`, `.class`, `[data-v-step]`) to find DOM elements. If a targeted element is not present in the DOM when a step attempts to show, the tour step will not appear or may throw an error.
Fix: Ensure the target element is rendered and available in the DOM before activating the tour step. If elements are conditionally rendered, use the `before` hook in the step to wait for the element or ensure its visibility. Use unique and stable selectors.
gotcha The `before` function within a tour step expects a Promise to be returned. If the promise is rejected, the tour will not proceed to that step. Forgetting to return a Promise or returning a non-Promise value can lead to unexpected behavior.
Fix: Always ensure the `before` function returns a Promise. Resolve the promise to allow the tour to proceed, and reject it to prevent advancement. For synchronous operations, use `Promise.resolve()`.
gotcha If you are using a bundler (e.g., Webpack, Rollup) and experience issues with Vue Tour's styles not applying, it's often due to the CSS import not being processed correctly or style isolation issues in your Vue components.
Fix: Ensure `import 'vue-tour/dist/vue-tour.css';` is present in your main application entry file (e.g., `main.js`/`main.ts`). Check your build configuration to confirm CSS files are handled by appropriate loaders (e.g., `vue-style-loader`, `css-loader`). Avoid scope conflicts if using `<style scoped>` extensively.

Install

npm install vue-tour npm
yarn add vue-tour yarn
pnpm add vue-tour pnpm

Imports

VueTour
wrong:
```
import { VueTour } from 'vue-tour';
```
correct:
```
import VueTour from 'vue-tour';
```
The main plugin is a default export, typically registered via `Vue.use()`.

CSS Stylesheet

wrong:

require('vue-tour/dist/vue-tour.css'); // While technically works in some setups, 'import' is idiomatic for modern Vue CLI/Vite projects.

correct:

import 'vue-tour/dist/vue-tour.css';

It is crucial to import the stylesheet for the tour's visual presentation. Ensure your build tool processes CSS imports correctly.

Vue.use()
wrong:
```
new Vue({ VueTour }); // Incorrect plugin registration.
```
correct:
```
Vue.use(VueTour);
```
The plugin must be explicitly installed into Vue using `Vue.use()` before any Vue instance is created.

Quickstart

Demonstrates the basic setup of Vue Tour in a Vue.js application, including plugin registration and CSS import.

import Vue from 'vue';
import App from './App.vue';
import VueTour from 'vue-tour';
import 'vue-tour/dist/vue-tour.css';

Vue.use(VueTour);

Vue.config.productionTip = false;

new Vue({
  render: h => h(App)
}).$mount('#app');

view raw JSON →