Plugins
Hook into a tour's lifecycle to block or resume starts, cancel or redirect steps, and subscribe to events.
Plugins are plain objects passed to createTour({ plugins }). The built-in persist and analytics are plugins too.
interface TourPlugin<TId extends string = string, TData = any> { name: string; setup?: (tour: Tour) => void | (() => void); beforeStart?: (tour: Tour, options: StartOptions) => MaybePromise<void | false | StartResult>; beforeStep?: (tour: Tour, transition: TransitionInfo) => MaybePromise<void | false | TId>;}Hooks
| Hook | Called | Return value |
|---|---|---|
setup |
Once, synchronously, inside createTour. |
Optional cleanup function, run by tour.destroy(). Use it to tour.on(…) / tour.subscribe(…). |
beforeStart |
On every start() (also restart(), goTo() on an inactive tour), before the first step is resolved. Receives the StartOptions. |
false blocks the start (status goes back to what it was). { stepId?, data? } resumes at a step and/or merges data. undefined continues normally. |
beforeStep |
Before every transition, before the previous step is left. Receives { from, to, direction, signal }; signal aborts when the transition is superseded. |
false cancels the transition (the current step stays). A step id redirects the transition there. undefined continues. |
Plugins run in array order. For beforeStart, an explicit start({ stepId }) takes precedence over a stepId returned by a plugin; for beforeStep, a redirect returned by one plugin is the to the following plugins receive.
Both async hooks are awaited. If the tour is started again (or another transition begins) while a hook is pending, its result is discarded.
TransitionInfo
| Field | Type | Description |
|---|---|---|
from |
TId | null |
Current step (null for the first step). |
to |
TId |
Requested step. |
direction |
'forward' | 'backward' | 'jump' |
How the step was requested. |
StartResult
| Field | Type | Description |
|---|---|---|
stepId |
TId |
Step to start at. |
data |
Partial<TData> |
Merged into the tour data. |
Examples
Only for signed-in users
import type { TourPlugin } from '@awesome-tour/core';
const requireUser = (getUser: () => { id: string } | null): TourPlugin => ({ name: 'require-user', beforeStart: () => (getUser() ? undefined : false),});Guard a step
const guardBilling: TourPlugin = { name: 'guard-billing', async beforeStep(tour, { to }) { if (to !== 'billing') return; const { canManageBilling } = await fetch('/api/me').then((r) => r.json()); return canManageBilling ? undefined : 'done'; // redirect },};Log to the console
const logger: TourPlugin = { name: 'logger', setup(tour) { const offs = [ tour.on('stepChange', (e) => console.debug(`[${tour.id}]`, e)), tour.on('error', ({ error }) => console.error(`[${tour.id}]`, error)), ]; return () => offs.forEach((off) => off()); },};
const tour = createTour({ id: 'onboarding', steps, plugins: [logger] });