Steps
Every field of a step definition, the target forms it accepts, and how missing targets and interactive steps behave.
A tour is a list of StepDefinition objects passed to createTour (or declared in JSX with <Tour.Step>, see Tour components).
{ id: 'create', route: '/projects', target: anchor('create-button'), when: (ctx) => ctx.data.role === 'admin', advanceOn: { event: 'click' }, onTargetMissing: 'skip',}StepDefinition
| Field | Type | Default | Description |
|---|---|---|---|
id |
TId extends string |
— | Required. Unique within the tour. Becomes part of the typed step-id union. |
target |
TargetInput | null |
— | What to highlight. Omit it (or pass null) for a centered step. See targets. |
when |
(ctx) => boolean | Promise<boolean> |
— | Conditional step: the step is skipped when it resolves to false. Errors count as false (and emit error). |
next |
TId | null | ((ctx) => TId | null | undefined) |
— | Branching. A step id jumps there; null completes the tour; undefined (from the function) falls back to the next visible step in order. |
route |
string |
— | Route the step lives on. If the current path doesn’t match, the tour navigates there first (patterns like /p/:id aren’t navigated to); the step stays hidden until the route matches. See router. |
advanceOn |
AdvanceOn | AdvanceOn[] |
— | Interactive step: advance when the user does something. See advanceOn. |
onTargetMissing |
'center' | 'wait' | 'skip' | 'error' |
tour’s, else 'center' |
Policy when the target can’t be found in time. See missing targets. |
targetTimeout |
number |
tour’s, else 3000 |
Milliseconds to wait for the target to appear. |
onTargetLost |
'reresolve' | 'center' | 'close' |
tour’s, else 'reresolve' |
Policy when the target leaves the page while the step is shown. See lost targets. |
scroll |
boolean | ScrollIntoViewOptions & { offset } |
tour’s, else true |
Scroll the target into view. Only scrolls when the targets aren’t already fully in the viewport. offset (number or per side) keeps it clear of sticky bars that set no scroll-padding. |
modal |
boolean |
tour’s modal |
Override modality for this step (used by the React components). |
beforeEnter |
(ctx) => void | Promise<void> |
— | Runs before the step is shown: after navigation, before target resolution. Await data loading, open a menu, etc. Throwing aborts the transition (error). |
enterTimeout |
number |
tour enterTimeout (none) |
Fail the transition when beforeEnter hasn’t settled after this many ms: the previous step stays and an error is emitted. |
afterLeave |
(ctx) => void | Promise<void> |
— | Runs (asynchronously) after the step is left — on navigation, close, skip, complete or pause. |
beforeLeave |
(ctx, { to, direction }) => boolean | void | Promise<…> |
— | Guard before leaving the step (to another step, or to: null to finish). Return false to stay. Not called by close, skip or pause. |
canNext |
(ctx) => boolean |
— | Whether the user may move forward yet. Re-checked live; exposed as state.canNext (Tour.Next is disabled) and enforced by next(). |
meta |
Record<string, unknown> |
— | Free-form metadata. Forwarded by the analytics plugin as event.meta. |
Transition order
When a step is entered the tour runs, in order:
- plugins’
beforeStep(may cancel or redirect), - the current step’s
beforeLeaveguard (may cancel), - the previous step’s
stepLeaveevent andafterLeave(statephase: 'transitioning'), - navigation to
route(if it doesn’t match), beforeEnter,- target resolution (
phase: 'resolving'while waiting, up totargetTimeout), - commit: the step becomes current and
stepChangeis emitted, - scroll into view, then
phase: 'ready'andadvanceOnlisteners are attached.
If another transition starts meanwhile (e.g. goTo while a target is loading), the in-flight one is aborted: ctx.signal fires and its result is discarded. Repeated next()/prev() calls while one is still resolving (a double-click on “Next”) are ignored, so beforeLeave runs once.
Each entered step is left exactly once: with onTargetMissing: 'skip' the tour hops over missing steps without re-running the previous step’s leave hooks. If a transition fails after step 3 (beforeEnter throws or times out, or onTargetMissing: 'error'), the previous step is put back on screen with its advanceOn and canNext listeners, and the failure is reported through the error event.
StepContext
Passed to when, next, beforeEnter, afterLeave and advanceOn.when.
| Field | Type | Description |
|---|---|---|
tour |
Tour |
The tour instance. |
step |
StepDefinition |
The step being evaluated. |
data |
TData |
Current tour data (tour.getState().data). |
signal |
AbortSignal |
Aborted when the transition is superseded. Pass it to fetch in async hooks. |
{ id: 'report', target: '#report', async beforeEnter({ signal }) { await fetch('/api/report/warmup', { signal }); },}Targets
TargetInput accepts several forms. All of them resolve to a list of nodes; several nodes are highlighted as one union rect.
| Form | Example | Notes |
|---|---|---|
| CSS selector | '#search', '[data-tour="nav"]' |
Matches every element (querySelectorAll). If nothing matches in the light DOM, open shadow roots are searched. |
| Element | document.querySelector('#nav') |
Must be connected to the document. |
| Ref | buttonRef |
Any { current: Element | null }, read at resolution time. |
| Anchor | anchor('create-button') |
Elements registered under that id (useTourAnchor, Tour.Anchor, registry.register). Preferred: no brittle selectors. See utilities. |
| Virtual element | { getBoundingClientRect: () => rect } |
Anything with a getBoundingClientRect() (Floating UI compatible). Optional contextElement. Used for canvas regions and 3D objects. |
| Function | () => document.querySelector('.row:last-child') |
Called on every resolution attempt; may return any other form, null or undefined. |
| Array | ['#stat-1', '#stat-3'] |
Union of all items (deduplicated). The tour waits for all items up to the timeout, then continues with whichever were found. |
Targets that aren’t there yet are awaited: the tour re-checks on DOM mutations, anchor registrations and every 100 ms until targetTimeout. While waiting, the state has phase: 'resolving'.
Missing targets
onTargetMissing decides what happens when the target still isn’t found after targetTimeout. A targetMissing event is emitted in every case.
| Policy | Behavior |
|---|---|
'center' |
Default. Show the step centered with no target; state.targetMissing is true (and React sets data-target-missing). |
'wait' |
Wait indefinitely (no timeout) for the target to appear. |
'skip' |
Move on: forward to the next visible step (completing the tour if there is none), or backward when navigating back. |
'error' |
Abort the transition and emit an error event (state.error is set). |
Lost targets
A target can also disappear after its step is shown: a list re-renders, a panel closes, a route
swaps the layout. The tour notices (one shared MutationObserver, plus anchor changes) and:
- looks the target up again — a re-rendered element is picked up silently;
- otherwise applies
onTargetLost:
| Policy | Behavior |
|---|---|
'reresolve' |
Default. Hide the step (phase: 'resolving') and wait up to targetTimeout for it to come back, then center it. |
'center' |
Keep the step on screen, centered (state.targetMissing). |
'close' |
Close the tour. |
A targetLost event ({ stepId, recovered }) is emitted either way. tour.refresh() still forces a re-resolve.
advanceOn
Makes a step interactive. One rule or an array of rules; the first rule that fires advances the tour (once).
| Field | Type | Description |
|---|---|---|
event |
string |
DOM event name ('click', 'input', 'submit'…). Listened on document in the capture phase; fires when the event happens inside the target. Shadow DOM aware. |
target |
TargetInput |
Where the event must happen. Default: the step’s resolved targets. |
when |
(ctx) => boolean |
Advance when the predicate becomes true. Re-checked on tour state changes, DOM mutations and every 200 ms. |
signal |
string |
Advance when the app calls tour.signal(name). |
delay |
number |
Advance automatically after this many ms on the step. Tour.Content gets data-auto-advance and --tour-auto-advance: <ms> for a countdown bar. |
to |
TId |
Go to this step instead of the regular next step. |
const steps = [ { id: 'intro', advanceOn: { delay: 4000 } }, // auto-advance after 4s { id: 'create', target: anchor('create'), advanceOn: { event: 'click' } }, { id: 'search', target: '#search', advanceOn: { when: () => document.querySelector<HTMLInputElement>('#search')!.value.length >= 3 }, }, { id: 'upload', target: '#dropzone', advanceOn: [ { signal: 'file-uploaded' }, // tour.signal('file-uploaded') from your upload handler { event: 'click', target: '#skip-upload', to: 'done' }, ], }, { id: 'done' },];Listeners are attached when the step becomes ready and removed when it is left.
React-only fields
ReactStepDefinition (from @awesome-tour/react) extends StepDefinition with fields rendered by the Tour components:
| Field | Type | Description |
|---|---|---|
title |
ReactNode |
Rendered by Tour.Title when it has no children. |
description |
ReactNode |
Rendered by Tour.Description when it has no children. |
content |
ReactNode | ((props: StepRenderProps) => ReactNode) |
Rendered by Tour.StepContent. The function form receives { tour, state, step }. |
side |
'top' | 'right' | 'bottom' | 'left' |
Preferred side for this step; overrides Tour.Content’s side. |
align |
'start' | 'center' | 'end' |
Preferred alignment for this step; overrides Tour.Content’s align. |
interactive |
boolean |
Let the user click/type into the highlighted target. Defaults to Tour.Root’s targetInteraction, else true when advanceOn.event is set. |
import type { ReactStepDefinition } from '@awesome-tour/react';
const steps = [ { id: 'search', target: '#search', side: 'bottom', interactive: true, title: 'Try the search', content: ({ state }) => <p>Step {state.progress.current} — type at least 3 characters.</p>, advanceOn: { when: () => document.querySelector<HTMLInputElement>('#search')!.value.length >= 3 }, },] satisfies ReactStepDefinition[];See also the guides on targets, interactive steps and branching.