Skip to content
awesome-tour

Type to search every page.

    BOnboarding checklistContents

    Onboarding checklist

    A persistent list of onboarding tasks completed by tours, signals or conditions.

    A checklist tracks onboarding across tours and what the user does in your app: “Learn the beat grid”, “Fill the bar”, “Bounce your first loop”. In the demo, each item completes a different way — with a tour, a predicate over the app’s state, a signal, and by hand. It is headless like tours: createChecklist holds the state, Checklist.* renders it.

    Onboarding checklist

    Getting started

    From an empty grid to your first bounce

    0 of 4 completed

    Make a beat0/3

    1. Not completed
    2. Locked: finish the previous steps first
    3. Locked: finish the previous steps first

    Release it0/1

    1. Locked: finish the previous steps first
    2. Not completed (optional)
    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
    ChecklistDemo.tsx
    import { createChecklist, createTour, memoryStorage, Tour } from '@awesome-tour/react';
    import { activeCells, connectAudio, createLoopwork, LoopworkApp, parts } from '@loopwork';
    import { RotateCcw } from 'lucide-react';
    import { useEffect } from 'react';
    import { ChecklistPanel } from '@/components/awesome-tour/checklist';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, worldButton } from './ui';
    const $ = parts('first-loop');
    const app = createLoopwork({ route: 'arrange' });
    const gridTour = createTour({
    id: 'docs-checklist-tour',
    steps: [
    {
    id: 'grid',
    target: $('sequencer'),
    title: 'The beat grid',
    description: 'One bar, sixteen steps. Click a cell to add a hit.',
    },
    {
    id: 'play',
    target: $('play'),
    title: 'Hear it',
    description: 'Finishing this tour checks the first item.',
    },
    ],
    });
    const checklist = createChecklist({
    id: 'docs-first-loop',
    persistence: memoryStorage(),
    sections: [
    { id: 'make', title: 'Make a beat' },
    { id: 'release', title: 'Release it' },
    ],
    items: [
    { id: 'tour', tour: gridTour, section: 'make', meta: { title: 'Learn the beat grid' } },
    {
    id: 'drums',
    after: 'tour', // locked until the tour is done
    section: 'make',
    // A predicate over your app's state, re-checked on `checklist.refresh()`.
    when: () => activeCells(app.getState()) >= 20,
    meta: { title: 'Fill the bar', description: '20 hits or more' },
    },
    {
    id: 'bass',
    after: 'tour',
    section: 'make',
    signal: 'bass-up',
    meta: { title: 'Bring the bass up', description: 'Bass at 60% or more' },
    },
    {
    id: 'bounce',
    after: ['drums', 'bass'],
    section: 'release',
    meta: { title: 'Bounce your first loop' },
    },
    {
    id: 'sound',
    optional: true, // a nice-to-have: doesn't count toward progress
    section: 'release',
    meta: { title: 'Turn the preview audio on' },
    },
    ],
    });
    // Your app reports progress: a signal, a refresh, or a manual completion.
    app.subscribe(() => checklist.refresh());
    app.on('level-changed', () => {
    if (app.getState().mixer.bass.level >= 0.6) checklist.signal('bass-up');
    });
    app.on('bounced', () => checklist.complete('bounce'));
    app.subscribe(() => {
    if (app.getState().sound) checklist.complete('sound');
    });
    export function ChecklistDemo() {
    useEffect(() => connectAudio(app), []);
    return (
    <DemoFrame
    title="Onboarding checklist"
    actions={
    <button
    type="button"
    className={worldButton.ghost}
    onClick={() => {
    checklist.reset();
    app.reset({ route: 'arrange' });
    }}
    >
    <RotateCcw aria-hidden="true" />
    Reset
    </button>
    }
    >
    <div className="grid gap-4">
    <ChecklistPanel
    checklist={checklist}
    description="From an empty grid to your first bounce"
    className="max-w-md"
    />
    <LoopworkApp scope="first-loop" app={app} layout="routed" />
    </div>
    <Tour.Root tour={gridTour}>
    <TourPopover />
    </Tour.Root>
    </DemoFrame>
    );
    }
    import { Checklist, createChecklist, localStorageAdapter } from '@awesome-tour/react';
    export const gettingStarted = createChecklist({
    id: 'getting-started',
    persistence: localStorageAdapter({ prefix: 'checklist:' }),
    onComplete: () => confetti(),
    items: [
    { id: 'tour', tour: 'onboarding', meta: { title: 'Take the product tour' } },
    { id: 'invite', signal: 'invited', meta: { title: 'Invite a teammate' } },
    { id: 'avatar', when: () => user.hasAvatar, meta: { title: 'Add a profile photo' } },
    { id: 'billing', meta: { title: 'Set up billing' } }, // completed manually
    ],
    });

    How items complete

    Item field Completes when…
    tour: 'onboarding' That tour completes. A tour id needs a TourProvider; a tour instance works anywhere.
    signal: 'invited' Your app calls gettingStarted.signal('invited').
    when: () => bool The predicate is true when gettingStarted.refresh() runs.
    — You call gettingStarted.complete('billing').

    Users can also skip(id) items, and dismiss() / restore() the whole checklist.

    Order, optional items and sections

    Real onboarding has an order: you can’t bounce a loop you haven’t made. after locks an item until its dependencies are done, optional keeps nice-to-haves out of the progress count, and section groups items under a heading:

    createChecklist({
    id: 'first-loop',
    sections: [{ id: 'make', title: 'Make a beat' }, { id: 'release', title: 'Release it' }],
    items: [
    { id: 'tour', tour: gridTour, section: 'make' },
    { id: 'drums', after: 'tour', section: 'make', when: () => hits() >= 20 },
    { id: 'bounce', after: ['drums'], section: 'release' },
    { id: 'sound', optional: true, section: 'release' },
    ],
    });

    state.next is the item to do next — put a “Continue” button on it. Locked items get data-locked, the next one data-next, and screen readers hear “Locked: finish the previous steps first” (the itemLocked message).

    Rendering

    <Checklist.Root checklist={gettingStarted} aria-labelledby="checklist-title">
    <h2 id="checklist-title">Getting started</h2>
    <Checklist.Progress>{({ completed, total }) => `${completed} of ${total}`}</Checklist.Progress>
    <Checklist.List>
    {gettingStarted.getItems().map((item) => (
    <Checklist.Item key={item.id} value={item.id}>
    <Checklist.ItemIndicator forceMount>✓</Checklist.ItemIndicator>
    <Checklist.ItemTrigger>{item.meta?.title as string}</Checklist.ItemTrigger>
    <Checklist.ItemSkip>Skip</Checklist.ItemSkip>
    </Checklist.Item>
    ))}
    </Checklist.List>
    <Checklist.Dismiss aria-label="Dismiss checklist">✕</Checklist.Dismiss>
    </Checklist.Root>
    • Checklist.ItemTrigger starts the item’s tour when it has one; add an onClick for anything else.
    • Items expose data-state="pending|done|skipped"; Checklist.Root sets --checklist-progress (0–1) for progress bars.
    • Checklist.Progress is a progressbar, and each trigger announces its status to screen readers.

    Hide the checklist once it’s dismissed with useStoreSelector(gettingStarted, (s) => s.dismissed). See the component reference and the checklist API.