useDriver
The useDriver composable provides driver.js tours with built-in localStorage persistence.
useDriver is auto-imported globally in your Nuxt application. Call it with a unique tour name and it returns a set of methods for controlling the tour and its played state.
Signature
const { start, restart, isPlayed, markPlayed, clear, driver } = useDriver(name, options?)
Parameters
name
- Type:
string - Required: yes
A unique identifier for this tour. Used to build the localStorage key: ${storagePrefix}:${name}.
options
- Type:
UseDriverOptions - Required: no
| Option | Type | Default | Description |
|---|---|---|---|
storageKey | string | "${storagePrefix}:${name}" | Fully override the localStorage key. |
autoSkip | boolean | false | When true, start() is a no-op if the tour has already been played. |
Return Value
start(config)
Initialises and drives the tour using the provided driver.js Config. When the driver is destroyed (tour completed or closed), the tour is automatically marked as played in localStorage.
const { start } = useDriver("onboarding");
onMounted(() => {
start({
showProgress: true,
steps: [
{ element: "#logo", popover: { title: "Logo", description: "This is our logo." } },
],
});
});
restart(config)
Clears the played flag from localStorage, then starts the tour unconditionally — regardless of the autoSkip option.
const { restart } = useDriver("onboarding");
function replayOnboarding() {
restart({ steps: [{ element: "#logo", popover: { title: "Welcome back!" } }] });
}
isPlayed()
Returns true if the localStorage key for this tour is set.
const { isPlayed } = useDriver("onboarding");
if (isPlayed()) {
console.log("User has already seen the onboarding tour.");
}
markPlayed()
Manually writes the played flag to localStorage without starting the tour.
const { markPlayed } = useDriver("onboarding");
// Mark as played without running the tour (e.g. for users who skipped setup)
markPlayed();
clear()
Removes the played flag from localStorage.
const { clear } = useDriver("onboarding");
// Reset on logout so new users see the tour
clear();
driver
The raw driver factory function from driver.js, exposed for advanced use cases that need direct access to the driver instance.
const { driver } = useDriver("onboarding");
const instance = driver({ steps: [] });
instance.drive();