Conditional steps & branching
Show steps only to some users, branch on answers and data, and hook into step lifecycle.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsMixer
4 channelsimport { 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.