Skip to content
awesome-tour

Type to search every page.

    BInteractive stepsContents

    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.

    Interactive steps
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    InteractiveDemo.tsx
    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.