How to Build a Product Tour in Vue.js — and What Stays Hard Afterwards

What You Are Actually Building

A product tour looks like one feature and is really five, each with its own failure mode. Most estimates cover the first two. The table below is the honest surface area — it is worth reading before you commit a sprint to it.

The five pieces of a Vue product tour, and the direction the data flows between them.

1. The Step Machine as a Composable

The instinct is to write <ProductTour :steps="steps" /> and mount it in App.vue. That works until something outside the component needs to start, stop or skip the tour — a button in a settings page, a route guard, an analytics callback. Then you are passing refs through provide/inject or reaching for a store.

Model the state as a composable instead. The component becomes a thin renderer over it, and anything in the app can drive the tour by importing one function.

import { ref, computed, shallowRef, readonly } from 'vue'

const steps      = shallowRef([])
const index      = ref(-1)
const targetEl   = shallowRef(null)
const status     = ref('idle')   // idle | running | paused | done

export function useTour() {
  const current  = computed(() => steps.value[index.value] ?? null)
  const isFirst  = computed(() => index.value === 0)
  const isLast   = computed(() => index.value === steps.value.length - 1)

  async function start(list) {
    steps.value  = list
    index.value  = 0
    status.value = 'running'
    await resolveCurrent()
  }

  async function next() {
    if (isLast.value) return finish('completed')
    index.value++
    await resolveCurrent()
  }

  function finish(reason) {
    status.value = 'done'
    targetEl.value = null
    emit('tour_' + reason, { step: index.value })
  }

  return {
    steps: readonly(steps), index: readonly(index),
    current, isFirst, isLast, status: readonly(status),
    targetEl: readonly(targetEl),
    start, next, finish,
  }
}

Two details matter here. shallowRef rather than ref for the DOM node: you want Vue to track the reference, not to walk a live DOM element making every property reactive — that is a real performance trap and a source of very confusing bugs. And readonly on the exported state, so a component cannot quietly reach in and set index.value without going through the transition logic that emits events.

2. Resolving Targets That Are Not There Yet

This is where most home-built Vue tours actually fail, and the failure is quiet. Your step says '#invoice-table'. The component that renders it is waiting on a fetch. document.querySelector returns null, the step renders with no anchor, and the tooltip lands in the top-left corner of the screen — or, worse, the tour stalls with an overlay up and no way out.

nextTick is necessary but not sufficient. It waits for Vue's current render flush, not for your API call. You need to wait for the element to appear in the document, with a deadline.

export function waitForElement(selector, { timeout = 5000 } = {}) {
  return new Promise((resolve) => {
    const found = document.querySelector(selector)
    if (found) return resolve(found)

    const observer = new MutationObserver(() => {
      const el = document.querySelector(selector)
      if (el) { cleanup(); resolve(el) }
    })

    const timer = setTimeout(() => { cleanup(); resolve(null) }, timeout)

    function cleanup() {
      observer.disconnect()
      clearTimeout(timer)
    }

    observer.observe(document.body, { childList: true, subtree: true })
  })
}

Note that it resolves with null rather than rejecting. A missing target is an expected condition, not an exception, and the calling code needs to make a product decision about it:

async function resolveCurrent() {
  const step = current.value
  if (!step) return

  await nextTick()
  const el = await waitForElement(step.target, { timeout: step.timeout ?? 5000 })

  if (!el) {
    emit('step_target_missing', { step: step.id, selector: step.target })
    if (step.optional) return next()      // skip it and carry on
    return finish('aborted')              // never leave the user behind an overlay
  }

  targetEl.value = el
  el.scrollIntoView({ block: 'center', behavior: 'smooth' })
  emit('step_viewed', { step: step.id })
}

3. Positioning the Step Tooltip

You can write positioning yourself: read getBoundingClientRect(), add the placement offset, clamp to the viewport, flip when there is no room. It is about eighty lines and it is correct until the target sits inside a scroll container, or a parent has a transform (which changes what position: fixed is relative to), or someone turns on RTL.

Use Floating UI. It is framework-agnostic, tiny, and it is the library Vue's own tooltip ecosystem settled on. The whole positioning layer becomes this:

import { computePosition, autoUpdate, offset, flip, shift, arrow } from '@floating-ui/dom'

const floating = ref(null)
const arrowEl  = ref(null)
let stopAutoUpdate = null

watch(() => [targetEl.value, current.value], async ([el]) => {
  stopAutoUpdate?.()
  if (!el || !floating.value) return

  // autoUpdate re-runs on scroll, resize, and layout shifts of any ancestor
  stopAutoUpdate = autoUpdate(el, floating.value, async () => {
    const { x, y, placement, middlewareData } = await computePosition(el, floating.value, {
      placement: current.value.placement ?? 'bottom',
      middleware: [
        offset(12),
        flip({ padding: 8 }),
        shift({ padding: 8 }),
        arrow({ element: arrowEl.value }),
      ],
    })
    Object.assign(floating.value.style, { left: `${x}px`, top: `${y}px` })
    // ...place the arrow from middlewareData.arrow
  })
}, { immediate: true })

onBeforeUnmount(() => stopAutoUpdate?.())

autoUpdate is the part people leave out and then spend a day debugging. Without it the tooltip is positioned once and then drifts away from its target the moment anything scrolls, an image loads, or a sidebar animates open.

4. The Spotlight Overlay

The classic approach is four absolutely-positioned divs forming a frame around the target. It works, the arithmetic is tedious, and rounded corners are impossible. An SVG mask is one element and handles the corners for free.

<template>
  <Teleport to="body">
    <svg v-if="rect" class="tour-overlay" :width="vw" :height="vh">
      <defs>
        <mask id="tour-hole">
          <rect :width="vw" :height="vh" fill="white" />
          <rect :x="rect.x - pad" :y="rect.y - pad"
                :width="rect.width + pad * 2" :height="rect.height + pad * 2"
                rx="8" fill="black" />
        </mask>
      </defs>
      <rect :width="vw" :height="vh" fill="rgba(12, 20, 40, 0.55)" mask="url(#tour-hole)" />
    </svg>
  </Teleport>
</template>

<style scoped>
.tour-overlay {
  position: fixed; inset: 0; z-index: 9998;
  pointer-events: none;          /* let the user click the highlighted control */
}
</style>

The <Teleport to="body"> is not optional. Render the overlay inside your component tree and the first ancestor with overflow: hidden, a transform, or a z-index stacking context will clip it — and you will conclude the mask is broken when the mask is fine.

Keep rect in sync with the same autoUpdate loop that drives the tooltip, so the hole and the tooltip never disagree about where the target is.

5. Surviving the Router, and Remembering

Vue Router is the piece the React version of this problem does not have in quite the same shape, because in Vue the router is usually the thing that swaps out whole subtrees. A tour that spans two routes must handle the transition explicitly.

const router = useRouter()

router.beforeEach((to, from, next) => {
  if (status.value === 'running') status.value = 'paused'
  next()
})

router.afterEach(async (to) => {
  if (status.value !== 'paused') return
  const step = current.value
  // Only resume if this step belongs on this route
  if (step.route && step.route !== to.name) return finish('aborted')
  status.value = 'running'
  await resolveCurrent()
})

Giving each step an optional route is worth the small extra config. Without it, a user who clicks a link mid-tour ends up on the billing page with a tooltip pointing at nothing, and your resolver's five-second timeout is the only thing that eventually rescues them.

Persistence: not localStorage alone

Almost every home-built tour stores tour_seen: true in localStorage. It is one line and it is wrong in a specific, reportable way: local storage is per-browser and per-device. The user who onboards on their laptop and opens the app on their desktop gets the whole tour again. So does anyone in a private window, anyone who clears site data, and every user in an organisation that resets browser profiles nightly.

async function markSeen(tourId, outcome) {
  try {
    await api.patch('/me/onboarding', { [tourId]: { outcome, at: new Date().toISOString() } })
  } catch {
    // network failure should not mean the user sees the tour twice today
    localStorage.setItem(`tour:${tourId}`, outcome)
  }
}

Record dismissed and completed separately. They are different signals: a tour people finish is working, a tour people escape from is a tax you are charging every new user. You cannot tell them apart from a single boolean.

What Stays Hard After It Works

The first version takes a couple of days and is genuinely satisfying. These are the items that turn up afterwards, in roughly the order teams hit them.

Build It, or Configure It?

Both answers are legitimate. The question is which problem you actually have.

The useful test is not "can we build this" — you can, it is a fortnight. It is: when the copy of step three needs changing, who does it, and how long until a user sees the change? If the honest answer is "a developer, next sprint", you have chosen the expensive option regardless of what the first estimate said. The full arithmetic is in build vs buy user onboarding.

A Pre-Launch Checklist

Whichever route you take, these are the things that separate a tour that helps from one that gets dismissed in two clicks.

1. Every step is skippable and the tour is escapable — including when a target is missing.
2. Selectors are data-tour attributes, not classes, and are checked in CI.
3. Events fire on every transition, so you can read per-step drop-off.
4. Completion is stored on the user, not only in localStorage.
5. Dismissed and completed are separate outcomes.
6. Keyboard: Escape closes, Tab is trapped, focus returns.
7. Tested at 375px and in your longest language.
8. The tour is short. Five steps that lead to one real action beat twelve that narrate the UI — the goal is activation, not a tour of the navigation.

Frequently Asked Questions