{"id":12638,"library":"vue3-tour","title":"Vue Tour for Vue 3","description":"`vue3-tour` is a lightweight, simple, and customizable tour plugin designed specifically for Vue.js 3 applications. It guides users through an application by highlighting elements and displaying contextual information in a step-by-step fashion. Currently at stable version 1.0.3, it is a direct fork of the popular `vue-tour` library, re-engineered for compatibility with the Vue 3 composition API and ecosystem. While release cadence isn't highly frequent, the project shows ongoing maintenance with recent fixes. Key differentiators include its ease of integration with Vue 3's `createApp` pattern, the ability to target any DOM element via standard CSS selectors, and support for asynchronous `before()` functions in steps for complex UI transitions. It ships with TypeScript types, enhancing developer experience in TypeScript projects.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/alexandreDavid/vue3-tour","tags":["javascript","vue","tour","typescript"],"install":[{"cmd":"npm install vue3-tour","lang":"bash","label":"npm"},{"cmd":"yarn add vue3-tour","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue3-tour","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Vue 3 integration","package":"vue","optional":false}],"imports":[{"note":"This is the default export for the plugin itself, used with `app.use()` to register the tour functionality globally.","wrong":"import { Vue3Tour } from 'vue3-tour'","symbol":"Vue3Tour","correct":"import Vue3Tour from 'vue3-tour'"},{"note":"The `<v-tour>` component is globally registered when the plugin is installed via `app.use(Vue3Tour)` and does not require explicit component import.","wrong":"import { VTour } from 'vue3-tour'","symbol":"v-tour","correct":"// Used directly in Vue templates as <v-tour ...>"},{"note":"Essential for default styling of the tour steps, popovers, and navigation. Customize by overriding these styles or importing your own.","wrong":"import 'vue3-tour/vue3-tour.css'","symbol":"styles","correct":"import 'vue3-tour/dist/vue3-tour.css'"},{"note":"Access the specific tour instance via the global property `$tours` on the Vue instance, using the `name` prop provided to the `<v-tour>` component.","wrong":"this.$tour.start()","symbol":"$tours","correct":"this.$tours['myTour'].start()"}],"quickstart":{"code":"// main.js\nimport { createApp } from 'vue';\nimport App from './App.vue';\nimport Vue3Tour from 'vue3-tour';\nimport 'vue3-tour/dist/vue3-tour.css';\n\nconst app = createApp(App);\napp.use(Vue3Tour);\napp.mount('#app');\n\n// App.vue\n<template>\n  <div>\n    <div id=\"v-step-0\" style=\"margin: 20px; padding: 10px; border: 1px solid blue;\">\n      A DOM element on your page. The first step will pop on this element.\n    </div>\n    <div class=\"v-step-1\" style=\"margin: 20px; padding: 10px; border: 1px solid green;\">\n      Another element for the second step.\n    </div>\n    <div data-v-step=\"2\" style=\"margin: 20px; padding: 10px; border: 1px solid red;\">\n      The final element for the third step.\n    </div>\n\n    <v-tour name=\"myTour\" :steps=\"steps\"></v-tour>\n    <button @click=\"startTour\">Start Guided Tour</button>\n  </div>\n</template>\n\n<script>\nexport default {\n  name: 'App',\n  data() {\n    return {\n      steps: [\n        {\n          target: '#v-step-0',\n          header: { title: 'Welcome!' },\n          content: `This is the starting point of our application tour.`,\n        },\n        {\n          target: '.v-step-1',\n          content: 'Here you will find key information and functionalities.',\n        },\n        {\n          target: '[data-v-step=\"2\"]',\n          content: 'And this is where you can take action!',\n          params: { placement: 'top' },\n        },\n      ],\n    };\n  },\n  methods: {\n    startTour() {\n      if (this.$tours && this.$tours['myTour']) {\n        this.$tours['myTour'].start();\n      } else {\n        console.error(\"Tour 'myTour' not found. Ensure <v-tour name='myTour'> is rendered.\");\n      }\n    },\n  },\n  mounted() {\n    // Optionally start the tour automatically\n    // this.startTour();\n  },\n};\n</script>","lang":"javascript","description":"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."},"warnings":[{"fix":"Rewrite tour components and plugin registration to align with Vue 3's `createApp` API and component lifecycle. Update imports and component usage accordingly.","message":"`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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Add `import 'vue3-tour/dist/vue3-tour.css'` to your application's entry point (e.g., `main.js` or `main.ts`).","message":"Tour popovers and navigation elements will appear unstyled or broken if the default CSS is not explicitly imported into your application.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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()`.","error":"TypeError: Cannot read properties of undefined (reading 'start') or TypeError: this.$tours is undefined"},{"fix":"Verify the import statement. It must be `import 'vue3-tour/dist/vue3-tour.css'`.","cause":"The import path for the CSS file is incorrect.","error":"Module not found: Error: Can't resolve 'vue3-tour/dist/vue3-tour.css'"},{"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.","cause":"The default CSS for `vue3-tour` has not been imported or has been inadvertently overridden by other styles.","error":"Tour steps are visible but lack styling (e.g., no arrows, misplaced popovers, basic browser button styling)."}],"ecosystem":"npm"}