Interactive steps
Advance the tour when the user clicks, types or completes an action.
The best onboarding teaches by doing. advanceOn makes a step wait for the user instead of a
“Next” button.
Loopworknight-drive.lwp
Beat A
16 steps · drumsKick
Snare
Hat
Clap
Mixer
4 channelsDrums
80%
Bass
35%
Keys
60%
Vox
50%
import { createTour, Tour } from '@awesome-tour/react';import { createLoopwork, emptyPattern, LoopworkApp, parts } from '@loopwork';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton } from './ui';
const $ = parts('first-beat');const app = createLoopwork({ pattern: emptyPattern() });const kicks = () => app.getState().pattern.kick.filter(Boolean).length;
const tour = createTour({ id: 'docs-interactive', steps: [ { id: 'kick', target: $('row-kick'), interactive: true, title: 'Lay down four kicks', description: 'Click any four cells in the kick row. Steps 1, 5, 9 and 13 are a classic.', // Advances by itself once the app's state says so. advanceOn: { when: () => kicks() >= 4 }, }, { id: 'bass', target: $('knob-bass'), interactive: true, side: 'left', title: 'Bring the bass up to 60%', description: 'Focus the knob and press ↑, or drag it upwards.', advanceOn: { when: () => app.getState().mixer.bass.level >= 0.6 }, }, { id: 'play', target: $('play'), interactive: true, title: 'Now play it', description: 'The app tells the tour when playback starts.', advanceOn: { signal: 'played' }, }, { id: 'done', title: 'That’s your first beat', description: 'Every step waited for you to do the thing, not to click Next.', }, ],});
// Your app reports what happened; the tour listens for the signal.app.on('play', () => tour.signal('played'));
export function InteractiveDemo() { return ( <Tour.Root tour={tour}> <DemoFrame title="Interactive steps" actions={<StartButton onClick={() => app.reset({ pattern: emptyPattern() })} />} > <LoopworkApp scope="first-beat" app={app} layout="compact" /> </DemoFrame> <TourPopover /> </Tour.Root> );}createTour({ id: 'create-project', steps: [ // 1. A DOM event on the target (or on advanceOn.target) { id: 'click', target: '#new', advanceOn: { event: 'click' } },
// 2. A predicate, re-checked on DOM mutations and on an interval { id: 'type', target: '#name', interactive: true, advanceOn: { when: () => document.querySelector<HTMLInputElement>('#name')!.value.length >= 3 }, },
// 3. A named signal from your app: tour.signal('saved') { id: 'save', target: '#save', interactive: true, advanceOn: { signal: 'saved' } },
{ id: 'done', title: 'Done!' }, ],});function SaveButton() { const { signal } = useTour(); return <button onClick={() => save().then(() => signal('saved'))}>Save</button>;}Options
advanceOn |
Type | Description |
|---|---|---|
event |
string |
DOM event that advances the tour. |
target |
TargetInput |
Where to listen for event. Default: the step’s resolved target. |
when |
(ctx) => boolean |
Advance when it becomes true. |
signal |
string |
Advance when the app calls tour.signal(name). |
to |
step id | Go to this step instead of the regular next one. |
Pass an array to accept several triggers — e.g. a click on either of two buttons, each with its own
to:
{ id: 'choose', target: ['#grid-view', '#list-view'], advanceOn: [ { event: 'click', target: '#grid-view', to: 'grid' }, { event: 'click', target: '#list-view', to: 'list' }, ],}Letting users reach the target
Modal tours block the page. A step’s target is clickable when the step is interactive: true
(implied when advanceOn.event is set). To make every target clickable, set
targetInteraction on Tour.Root.
You can still render Tour.Next on an interactive step to let users move on without doing the
action — or leave it out to require it.