Skip to content
awesome-tour

Type to search every page.

    BConditional steps & branchingContents

    Conditional steps & branching

    Show steps only to some users, branch on answers and data, and hook into step lifecycle.

    Branching
    Loopworknight-drive.lwp
    001.1.1
    1. 1
    2. 2
    3. 3
    4. 4
    5. 5
    6. 6
    7. 7
    8. 8
    Drums
    Beat A
    Beat B
    Bass
    Sub line
    Keys
    Rhodes
    Vox
    Hook (dry)

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    BranchingDemo.tsx
    import { createTour, Tour, useTour } from '@awesome-tour/react';
    import { LoopworkApp, parts } from '@loopwork';
    import { Disc3, Drum, Mic } from 'lucide-react';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { Button } from '@/components/ui/button';
    import { DemoFrame, StartButton } from './ui';
    const $ = parts('branches');
    interface Data {
    making: 'beats' | 'podcast' | 'dj' | null;
    }
    const CHOICES = [
    { id: 'beats', label: 'Beats', icon: Drum },
    { id: 'podcast', label: 'A podcast', icon: Mic },
    { id: 'dj', label: 'A DJ set', icon: Disc3 },
    ] as const;
    function MakingPicker() {
    const { setData, next } = useTour<Data>();
    return (
    <div className="mt-1 grid grid-cols-3 gap-2">
    {CHOICES.map(({ id, label, icon: Icon }) => (
    <Button
    key={id}
    variant="outline"
    className="h-auto flex-col gap-1 py-2"
    onClick={() => {
    setData({ making: id });
    void next();
    }}
    >
    <Icon />
    {label}
    </Button>
    ))}
    </div>
    );
    }
    const tour = createTour({
    id: 'docs-branching',
    data: { making: null } as Data,
    steps: [
    {
    id: 'making',
    title: 'What are you making?',
    description: 'We’ll show you the part of Loopwork you need first.',
    content: <MakingPicker />,
    next: (ctx) =>
    (({ beats: 'beat', podcast: 'voice', dj: 'tempo' }) as const)[ctx.data.making ?? 'beats'],
    },
    {
    id: 'beat',
    target: $('sequencer'),
    title: 'Start with the beat',
    description: 'Sixteen steps per bar. Click to add hits.',
    next: 'mixer',
    },
    {
    id: 'voice',
    target: $('lane-vox'),
    title: 'Your voice lives on Vox',
    description: 'It’s muted in this project: unmute it in the mixer before you record.',
    next: 'done',
    },
    {
    id: 'tempo',
    target: $('bpm'),
    title: 'Match your set’s tempo',
    description: 'Type the BPM of the track you’re mixing into.',
    next: 'mixer',
    },
    {
    id: 'mixer',
    target: $('mixer'),
    side: 'left',
    // Never shown to podcasters, whatever path leads here.
    when: (ctx) => ctx.data.making !== 'podcast',
    title: 'Balance the channels',
    description: 'Press Back: it walks the path you actually took.',
    },
    {
    id: 'done',
    title: 'You’re set up',
    description: 'Every branch above is a plain function of the tour’s data.',
    },
    ],
    });
    export function BranchingDemo() {
    return (
    <Tour.Root tour={tour}>
    <DemoFrame title="Branching" actions={<StartButton />}>
    <LoopworkApp scope="branches" />
    </DemoFrame>
    <TourPopover />
    </Tour.Root>
    );
    }

    Tour data

    Every tour carries typed data — the user’s role, answers from a step, feature flags. Read it in when, next and lifecycle hooks via ctx.data; update it with tour.setData().

    interface Data {
    making: 'beats' | 'podcast' | null;
    }
    const tour = createTour({
    id: 'welcome',
    data: { making: null } as Data,
    steps: [
    {
    id: 'making',
    title: 'What are you making?',
    content: <MakingPicker />, // calls setData({ making }) then next()
    next: (ctx) => (ctx.data.making === 'podcast' ? 'voice' : 'beat'),
    },
    { id: 'beat', target: '#sequencer', next: 'mixer' },
    { id: 'voice', target: '#lane-vox', next: null }, // null completes the tour
    { id: 'mixer', target: '#mixer', when: (ctx) => ctx.data.making !== 'podcast' },
    ],
    });
    function MakingPicker() {
    const { setData, next } = useTour<Data>();
    return (
    <button onClick={() => { setData({ making: 'podcast' }); next(); }}>A podcast</button>
    );
    }

    Start with data from your app: tour.start({ data: { making: user.goal } }).

    Conditional steps — when

    A step whose when(ctx) returns false is skipped, in either direction. It may be async (e.g. check a feature flag); progress (Step 2 of 5) counts only visible steps.

    Branching — next

    • next: 'stepId' — jump to a fixed step.
    • next: (ctx) => 'stepId' — decide at runtime.
    • next: null — complete the tour after this step.

    Back goes back the way you came. prev() walks the history of steps actually visited, so after a branch, “Back” returns to the branching step — not to the previous item in the array.

    Lifecycle hooks

    {
    id: 'settings',
    route: '/settings',
    target: '#danger-zone',
    // Runs after navigation, before the target is resolved.
    beforeEnter: async (ctx) => {
    await openSettingsPanel({ signal: ctx.signal });
    },
    afterLeave: () => closeSettingsPanel(),
    }

    Transitions are cancellable: if the user clicks “Next” twice, the first transition is aborted and ctx.signal (an AbortSignal) fires — pass it to fetch or check it in long hooks.

    For cross-cutting rules (block steps, redirect, A/B tests) use a plugin with beforeStep.