Nuxt Driver.js

A Nuxt module that wraps driver.js and adds persistent tour tracking via localStorage. Guide your users through your Nuxt application with multi-step tours that remember where they left off.

• ✨  Release Notes
• 📖  Documentation
• 🤝  Contributing

Deployment Status

Features

• Tour persistence — completed tours are stored in localStorage so they are not replayed on every page load.
• Restart support — programmatically clear a tour's played state and replay it at any time.
• Auto-skip — optionally skip a tour silently if the user has already completed it.
• Easy to use — one auto-imported composable, zero boilerplate.
• Customizable — every driver.js option is available.
• Responsive — works on all devices and screen sizes.

Quick Setup

bun add nuxt-driver.js

Add the module to your nuxt.config:

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

useDriver Composable

const { start, restart, isPlayed, markPlayed, clear, driver } = useDriver(name, options?)

Parameters

Parameter	Type	Description
name	string	Unique identifier for the tour. Used as part of the localStorage key.
options	UseDriverOptions	Optional configuration (see below).

UseDriverOptions

Option	Type	Default	Description
storageKey	string	"${storagePrefix}:${name}"	Fully override the localStorage key.
autoSkip	boolean	false	Skip start() silently when the tour has already been played.

Return Value

Member	Type	Description
start(config)	(config: Config) => void	Start the tour. Marks as played on completion.
restart(config)	(config: Config) => void	Clear the played flag and start unconditionally.
isPlayed()	() => boolean	Returns true if the tour has been completed.
markPlayed()	() => void	Manually write the played flag to localStorage.
clear()	() => void	Remove the played flag from localStorage.
driver	(options?: Config) => Driver	Raw driver.js factory for advanced use.

Example

<script setup lang="ts">
onMounted(() => {
  const { start } = useDriver("onboarding", { autoSkip: true });

  start({
    showProgress: true,
    animate: true,
    steps: [
      {
        element: "#welcome",
        popover: {
          title: "Welcome",
          description: "Let us show you around.",
          side: "bottom",
        },
      },
      {
        element: "#dashboard",
        popover: {
          title: "Your Dashboard",
          description: "Everything you need in one place.",
          side: "right",
        },
      },
    ],
  });
});
</script>

Restart a Tour

<script setup lang="ts">
const { restart } = useDriver("onboarding");

function replayTour() {
  restart({
    steps: [
      { element: "#welcome", popover: { title: "Welcome back!" } },
    ],
  });
}
</script>

<template>
  <button @click="replayTour">Replay tour</button>
</template>

Module Options

Configure the module in nuxt.config under the driverJs key:

export default defineNuxtConfig({
  modules: ["nuxt-driver.js"],
  driverJs: {
    storagePrefix: "my-app", // default: "nuxt-driver"
  },
});

Option	Type	Default	Description
storagePrefix	string	"nuxt-driver"	Prefix for all localStorage tour keys.

Contribution

See CONTRIBUTING.md for the full development guide.

# Install dependencies
bun install

# Generate type stubs and prepare the playground
bun run dev:prepare

# Start the playground dev server
bun run dev

# Run linting (ESLint + oxlint)
bun run lint

# Format with oxfmt
bun run fmt

# Run tests
bun run test

# Release (maintainers only)
bun run release