Vue Tour for Vue 3

Common errors

• TypeError: Cannot read properties of undefined (reading 'start') or TypeError: this.$tours is undefined

  cause The `v-tour` component, which registers the tour instance with the given name, has not been rendered or the plugin was not correctly installed via `app.use()`.
  fix Ensure `app.use(Vue3Tour)` is called in your `main.js/ts` file and that the `<v-tour name="yourTourName" :steps="steps"></v-tour>` component is present and rendered in your application's template hierarchy.

• Module not found: Error: Can't resolve 'vue3-tour/dist/vue3-tour.css'

  cause The import path for the CSS file is incorrect.
  fix Verify the import statement. It must be `import 'vue3-tour/dist/vue3-tour.css'`.

• Tour steps are visible but lack styling (e.g., no arrows, misplaced popovers, basic browser button styling).

  cause The default CSS for `vue3-tour` has not been imported or has been inadvertently overridden by other styles.
  fix Add `import 'vue3-tour/dist/vue3-tour.css'` to your application's entry file. If already present, inspect your application's styles for conflicts that might be overriding `vue3-tour`'s default CSS rules.

Warnings

• breaking `vue3-tour` is a complete rewrite for Vue 3 and is incompatible with applications built for Vue 2 using the original `vue-tour` library. Direct migration requires updating plugin registration and component usage to Vue 3's API.
  Fix: Rewrite tour components and plugin registration to align with Vue 3's `createApp` API and component lifecycle. Update imports and component usage accordingly.
• gotcha Tour popovers and navigation elements will appear unstyled or broken if the default CSS is not explicitly imported into your application.
  Fix: Add `import 'vue3-tour/dist/vue3-tour.css'` to your application's entry point (e.g., `main.js` or `main.ts`).
• gotcha If a tour step's `target` selector (e.g., `#my-id`, `.my-class`, `[data-v-step="2"]`) does not match an existing DOM element when the step is activated, the tour step will fail to render correctly or may throw an error.
  Fix: Ensure the DOM element targeted by a step is rendered and available before `this.$tours['yourTour'].start()` or `nextStep()` is called. Utilize the `before()` hook within steps for asynchronous UI preparation if elements are conditionally rendered or loaded.

Install

• npm install vue3-tour npm
• yarn add vue3-tour yarn
• pnpm add vue3-tour pnpm

Imports

• Vue3Tour
  wrong:

  import { Vue3Tour } from 'vue3-tour'

  correct:

  import Vue3Tour from 'vue3-tour'

  This is the default export for the plugin itself, used with `app.use()` to register the tour functionality globally.
• v-tour
  wrong:

  import { VTour } from 'vue3-tour'

  correct:

  // Used directly in Vue templates as <v-tour ...>

  The `<v-tour>` component is globally registered when the plugin is installed via `app.use(Vue3Tour)` and does not require explicit component import.
• styles
  wrong:

  import 'vue3-tour/vue3-tour.css'

  correct:

  import 'vue3-tour/dist/vue3-tour.css'

  Essential for default styling of the tour steps, popovers, and navigation. Customize by overriding these styles or importing your own.
• $tours
  wrong:

  this.$tour.start()

  correct:

  this.$tours['myTour'].start()

  Access the specific tour instance via the global property `$tours` on the Vue instance, using the `name` prop provided to the `<v-tour>` component.

Quickstart

Demonstrates how to install `vue3-tour`, register the plugin, include necessary styles, define tour steps targeting specific DOM elements, and programmatically start a guided tour.

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import Vue3Tour from 'vue3-tour';
import 'vue3-tour/dist/vue3-tour.css';

const app = createApp(App);
app.use(Vue3Tour);
app.mount('#app');

// App.vue
<template>
  <div>
    <div id="v-step-0" style="margin: 20px; padding: 10px; border: 1px solid blue;">
      A DOM element on your page. The first step will pop on this element.
    </div>
    <div class="v-step-1" style="margin: 20px; padding: 10px; border: 1px solid green;">
      Another element for the second step.
    </div>
    <div data-v-step="2" style="margin: 20px; padding: 10px; border: 1px solid red;">
      The final element for the third step.
    </div>

    <v-tour name="myTour" :steps="steps"></v-tour>
    <button @click="startTour">Start Guided Tour</button>
  </div>
</template>

<script>
export default {
  name: 'App',
  data() {
    return {
      steps: [
        {
          target: '#v-step-0',
          header: { title: 'Welcome!' },
          content: `This is the starting point of our application tour.`,
        },
        {
          target: '.v-step-1',
          content: 'Here you will find key information and functionalities.',
        },
        {
          target: '[data-v-step="2"]',
          content: 'And this is where you can take action!',
          params: { placement: 'top' },
        },
      ],
    };
  },
  methods: {
    startTour() {
      if (this.$tours && this.$tours['myTour']) {
        this.$tours['myTour'].start();
      } else {
        console.error("Tour 'myTour' not found. Ensure <v-tour name='myTour'> is rendered.");
      }
    },
  },
  mounted() {
    // Optionally start the tour automatically
    // this.startTour();
  },
};
</script>