Nuxt Tour

Add interactive guided tours to your Nuxt app. nuxt-tour gives you a fully-featured <VTour /> component and a useTour() composable so you can drive tours from anywhere in your code.

• 📖  Documentation
• ✨  Release Notes
• 🤝  Contributing

Features

• Component + Composable — use <VTour /> declaratively or control tours programmatically with useTour()
• Smart localStorage — three storage modes: 'end' (default), 'step' (resume mid-tour), or 'never'; supports TTL expiry and version-based resets
• Keyboard navigation — arrow keys to move between steps, Escape to exit
• Highlight & backdrop — spotlight the target element with an outline and an optional dark overlay
• Fully customisable — every piece of the tooltip is a named slot; styling is done with CSS custom properties (--nt-*), no Sass required
• SSR safe — all browser APIs are guarded behind import.meta.client
• Accessible — focus trap, scroll lock, and role="tooltip" out of the box

Quick Setup

# npm
npm install nuxt-tour

# bun
bun add nuxt-tour

Add the module to your nuxt.config:

export default defineNuxtConfig({
  modules: ["nuxt-tour"],
});

Basic Usage

Define your steps and drop in the component:

<template>
  <div>
    <h1 class="hero-title">Welcome</h1>
    <button class="cta">Get started</button>

    <VTour :steps="steps" auto-start />
  </div>
</template>

<script setup lang="ts">
import type { TourStep } from "#nuxt-tour/types";

const steps: TourStep[] = [
  {
    target: ".hero-title",
    title: "Welcome to the app",
    body: "This is your dashboard. Let us show you around.",
  },
  {
    target: ".cta",
    title: "Ready to go?",
    body: "Click here whenever you want to get started.",
  },
];
</script>

Composable Usage

Control a tour from anywhere — even before the component mounts:

const { isPlayed, start, reset, currentStep, isActive } = useTour("onboarding");

// Show a "Replay tour" button only after the tour has been completed
if (!isPlayed.value) {
  await start();
}

Module Options

export default defineNuxtConfig({
  modules: ["nuxt-tour"],
  tour: {
    // Component name prefix. Default "V" → <VTour />
    prefix: "V",

    // Inject the default stylesheet. Set false to bring your own.
    injectCSS: true,

    // localStorage key prefix. Default "nt" → key "nt-onboarding"
    storagePrefix: "nt",

    // Bump this string to force all previously-played tours to show again.
    storageVersion: "v2",
  },
});

Key Props

| Prop | Type | Default | Description | |---|---|---|---| | steps | TourStep[] | — | Step definitions (required) | | name | string | "default" | Unique tour name — used as the localStorage key | | autoStart | boolean | false | Start the tour on mount | | saveToLocalStorage | 'end' \| 'step' \| 'never' | 'end' | When to persist progress | | ttl | number | — | Days before a completed tour shows again | | highlight | boolean | false | Outline the target element | | backdrop | boolean | false | Show a dark overlay | | showProgress | boolean | false | Show "Step N of M" counter | | keyboard | boolean | true | Arrow-key and Escape navigation | | scrollBehavior | 'jump' \| 'smooth' \| 'none' | 'jump' | How to scroll to each step | | trapFocus | boolean | true | Trap keyboard focus inside the tooltip | | lockScroll | boolean | true | Prevent page scrolling while the tour is active |

Customising Styles

Override any --nt-* CSS custom property on #nt-tooltip:

#nt-tooltip {
  --nt-bg: #1e1e2e;
  --nt-text: #cdd6f4;
  --nt-border-color: #45475a;
  --nt-btn-bg: #cba6f7;
  --nt-btn-color: #1e1e2e;
  --nt-radius: 10px;
}

Emits

| Event | Payload | Description | |---|---|---| | tour:start | — | Tour has begun | | tour:end | — | Tour completed | | tour:skip | — | Tour was skipped | | tour:step-change | { from, to } | Step changed |

Exposed Methods

const tour = useTemplateRef("tour");

tour.value?.startTour();
tour.value?.endTour();
tour.value?.skipTour();
tour.value?.nextStep();
tour.value?.prevStep();
tour.value?.goToStep(2);
tour.value?.pause();
tour.value?.resume();
tour.value?.resetTour();

Contributing

See CONTRIBUTING.md for local dev setup, coding standards, and the PR checklist.