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.
Getting started
From an empty grid to your first bounce
Make a beat0/3
- Not completed
- Locked: finish the previous steps first
- Locked: finish the previous steps first
Release it0/1
- Locked: finish the previous steps first
- Not completed (optional)
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsimport { 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.ItemTriggerstarts the item’s tour when it has one; add anonClickfor anything else.- Items expose
data-state="pending|done|skipped";Checklist.Rootsets--checklist-progress(0–1) for progress bars. Checklist.Progressis aprogressbar, 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.