createTour
Create a headless, framework-agnostic tour instance from a list of steps.
import { createTour } from '@awesome-tour/core';createTour(options) returns a Tour instance: an immutable state snapshot (getState / subscribe), an event emitter (on) and imperative controls (start, next, prev, goTo…). It doesn’t touch the DOM until it is started, and it works without React.
Example
import { anchor, createTour, localStorageAdapter, persist } from '@awesome-tour/core';
interface OnboardingData { role: 'admin' | 'member';}
export const onboarding = createTour({ id: 'onboarding', version: 2, data: { role: 'member' } as OnboardingData, plugins: [persist(localStorageAdapter())], steps: [ { id: 'welcome' }, // no target → centered { id: 'nav', target: anchor('nav') }, { id: 'admin', target: '#admin', when: (ctx) => ctx.data.role === 'admin' }, { id: 'done' }, ],});
onboarding.start();Options
| Option | Type | Default | Description |
|---|---|---|---|
id |
string |
— | Required. Unique id. Used by TourProvider / the manager to look the tour up, and as the default persistence key. |
steps |
readonly TStep[] |
— | Required. The step definitions, in order. |
version |
number |
1 |
Bump it when the tour changes meaningfully: persisted progress saved with another version is discarded by persist. |
data |
TData |
{} |
Initial tour data. Available to when, next, advanceOn.when etc. as ctx.data; update it with tour.setData(). |
modal |
boolean |
true |
Modal tours block the page (overlay, focus trap, rest of the page inert). Steps can override it with step.modal. |
plugins |
readonly TourPlugin[] |
[] |
Plugins such as persist() and analytics(). Run in order. |
router |
RouterAdapter |
— | Router adapter for steps with a route. Usually injected by TourProvider instead. |
anchors |
AnchorRegistry |
defaultAnchors |
Registry used to resolve anchor(id) targets. See utilities. |
targetTimeout |
number |
3000 |
How long (ms) to wait for a missing target before applying onTargetMissing. Per-step targetTimeout wins. |
enterTimeout |
number |
— | Fail a transition whose beforeEnter hasn’t settled after this many ms. Per-step enterTimeout wins. |
preview |
boolean |
false |
A draft: saves no progress or impressions, sends no analytics, ignores display rules. Set by previewFromUrl. |
goal |
TourGoal |
— | The conversion the tour is for: { name?, signal?, event?, route?, when?, within? }. Watched from each start, even after the tour ends; emits goal. See Goals. |
onTargetMissing |
'center' | 'wait' | 'skip' | 'error' |
'center' |
What to do when a target isn’t found in time. Per-step onTargetMissing wins. See missing targets. |
scroll |
boolean | ScrollIntoViewOptions |
true |
Scroll targets into view when a step is shown. Options are merged over { block: 'center', inline: 'nearest' }. Per-step scroll wins. |
Type parameters
function createTour<const TStep extends StepDefinition<TData, string>, TData = Record<string, unknown>>( options: TourOptions<TStep, TData>,): Tour<TStep, TData>;TStep is inferred with a const type parameter, so step ids become a string-literal union. Methods that take a step id are checked against it:
const tour = createTour({ id: 'demo', steps: [{ id: 'welcome' }, { id: 'search', target: '#search' }],});
tour.goTo('search'); // ✅tour.goTo('serch'); // ❌ Type error: '"serch"' is not assignable to '"welcome" | "search"'tour.getState().stepId; // "welcome" | "search" | nullTData is inferred from data. Cast the initial value ({ role: 'member' } as OnboardingData) to widen it, as in the example above.
In React, annotate steps with ReactStepDefinition to get title, description, content, side, align and interactive:
import { createTour, type ReactStepDefinition } from '@awesome-tour/react';
const steps = [ { id: 'welcome', title: 'Welcome', description: 'A quick look around.' }, { id: 'nav', target: '#nav', side: 'right', title: 'Navigation' },] satisfies ReactStepDefinition<OnboardingData>[];
export const onboarding = createTour({ id: 'onboarding', steps, data: { role: 'member' } as OnboardingData });Lifecycle notes
- Plugins’
setupruns synchronously insidecreateTour. - The tour starts in the
idlestatus and does nothing untilstart()is called (directly, throughTour.Trigger,defaultOpen, the manager or a checklist). - Call
tour.destroy()when you no longer need the tour: it aborts in-flight transitions, runs plugin cleanups, removes event handlers and unsubscribes from the router.