{"id":12610,"library":"vue-tour","title":"Vue Tour","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/pulsardev/vue-tour","tags":["javascript","vue","tour","typescript"],"install":[{"cmd":"npm install vue-tour","lang":"bash","label":"npm"},{"cmd":"yarn add vue-tour","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-tour","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for positioning tour steps. Breaking changes related to Popper.js v2.x were introduced in vue-tour v2.0.0.","package":"popper.js","optional":false}],"imports":[{"note":"The main plugin is a default export, typically registered via `Vue.use()`.","wrong":"import { VueTour } from 'vue-tour';","symbol":"VueTour","correct":"import VueTour from 'vue-tour';"},{"note":"It is crucial to import the stylesheet for the tour's visual presentation. Ensure your build tool processes CSS imports correctly.","wrong":"require('vue-tour/dist/vue-tour.css'); // While technically works in some setups, 'import' is idiomatic for modern Vue CLI/Vite projects.","symbol":"CSS Stylesheet","correct":"import 'vue-tour/dist/vue-tour.css';"},{"note":"The plugin must be explicitly installed into Vue using `Vue.use()` before any Vue instance is created.","wrong":"new Vue({ VueTour }); // Incorrect plugin registration.","symbol":"Vue.use()","correct":"Vue.use(VueTour);"}],"quickstart":{"code":"import Vue from 'vue';\nimport App from './App.vue';\nimport VueTour from 'vue-tour';\nimport 'vue-tour/dist/vue-tour.css';\n\nVue.use(VueTour);\n\nVue.config.productionTip = false;\n\nnew Vue({\n  render: h => h(App)\n}).$mount('#app');\n","lang":"typescript","description":"Demonstrates the basic setup of Vue Tour in a Vue.js application, including plugin registration and CSS import."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=1.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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']`.","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()`.","error":"TypeError: Cannot read properties of undefined (reading 'start') OR TypeError: this.$tours[tourName] is undefined"},{"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.","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`.","error":"Popper: `modifiers.popperOffsets.offset` (or similar property) is not a valid Popper.js v2 option."},{"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.","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.","error":"Error: [Vue warn]: The client-side rendered virtual DOM tree is not matching server-rendered content. This is likely caused by incorrect HTML markup"}],"ecosystem":"npm"}