Checklist
A styled onboarding checklist — progress, completion states and a dismiss/restore flow.
Getting started
From an empty grid to your first bounce
0 of 4 completed
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)
Loopworknight-drive.lwp
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Drums
Beat A
Beat B
Bass
Sub line
Keys
Rhodes
Vox
Hook (dry)
Beat A
16 steps · drumsKick
Snare
Hat
Clap
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> );}Installation
pnpm dlx shadcn@latest add @awesome-tour/checklistnpx shadcn@latest add @awesome-tour/checklistUsage
import { ChecklistPanel } from '@/components/awesome-tour/checklist';
<ChecklistPanel checklist={gettingStarted} title="Getting started" description="3 quick wins to get going"/>Item titles and descriptions are read from meta.title / meta.description; pass renderItem to
map them differently. Once dismissed, the panel becomes a “Show checklist” button.
Parts: ChecklistCard, ChecklistHeader, ChecklistProgressBar, ChecklistItems, ChecklistRow.
Source
'use client';
import { Checklist, type ChecklistInstance, type ChecklistItemDefinition, type ChecklistRootProps, useStoreSelector, useTourMessages,} from '@awesome-tour/react';import { Check, ChevronRight, Lock, Minus, X } from 'lucide-react';import type * as React from 'react';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';
function ChecklistCard({ className, ...props }: ChecklistRootProps) { return ( <Checklist.Root data-slot="checklist" className={cn( 'flex flex-col gap-4 rounded-xl border bg-card p-4 text-sm text-card-foreground shadow-sm', className, )} {...props} /> );}
function ChecklistHeader({ className, title, description, dismissible = true, titleId,}: { className?: string; title: React.ReactNode; description?: React.ReactNode; dismissible?: boolean; /** Id for the heading, to label the root with `aria-labelledby`. */ titleId?: string;}) { const { dismissChecklist } = useTourMessages(); return ( <div data-slot="checklist-header" className={cn('flex items-start gap-2', className)}> <div className="flex min-w-0 flex-1 flex-col gap-0.5"> <h2 id={titleId} className="text-sm leading-none font-semibold"> {title} </h2> {description && <p className="text-xs text-muted-foreground">{description}</p>} </div> {dismissible && ( <Checklist.Dismiss asChild> <Button variant="ghost" size="icon-xs" aria-label={dismissChecklist} className="-mt-1 -mr-1 text-muted-foreground" > <X /> </Button> </Checklist.Dismiss> )} </div> );}
/** Progress label + bar driven by `--checklist-progress`. */function ChecklistProgressBar({ className }: { className?: string }) { const { checklistValue } = useTourMessages(); return ( <Checklist.Progress data-slot="checklist-progress" className={cn('flex flex-col gap-1.5', className)} > {({ completed, total }) => ( <> <span className="text-xs text-muted-foreground tabular-nums"> {checklistValue(completed, total)} </span> <span aria-hidden="true" className="h-1.5 overflow-hidden rounded-full bg-muted"> <span className="block h-full w-[calc(var(--checklist-progress)*100%)] rounded-full bg-primary transition-[width] duration-500 ease-out" /> </span> </> )} </Checklist.Progress> );}
function ChecklistItems({ className, ...props }: React.ComponentProps<typeof Checklist.List>) { return ( <Checklist.List data-slot="checklist-items" className={cn('-mx-2 flex flex-col gap-0.5', className)} {...props} /> );}
function ChecklistRow({ value, title, description, className,}: { value: string; title: React.ReactNode; description?: React.ReactNode; className?: string;}) { return ( <Checklist.Item value={value} data-slot="checklist-row" className={cn( 'group/item relative flex items-center gap-3 rounded-lg', // What to do next stands out; locked items recede until their turn. 'data-[next]:bg-accent/60 data-[locked]:opacity-60', className, )} > <Checklist.ItemIndicator forceMount className={cn( 'pointer-events-none absolute left-2 flex size-5 shrink-0 items-center justify-center rounded-full border-2 border-muted-foreground/30 transition-colors', 'group-data-[state=done]/item:border-primary group-data-[state=done]/item:bg-primary group-data-[state=done]/item:text-primary-foreground', 'group-data-[state=skipped]/item:border-muted-foreground/40 group-data-[state=skipped]/item:bg-muted', '[&_svg]:size-3 [&_svg]:stroke-3', )} > <Check className="hidden group-data-[state=done]/item:block" /> <Minus className="hidden group-data-[state=skipped]/item:block" /> </Checklist.ItemIndicator> <Checklist.ItemTrigger className={cn( 'flex w-full cursor-pointer items-center gap-3 rounded-lg py-2 pr-2 pl-10 text-left outline-none transition-colors', 'hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50', 'data-[locked]:cursor-not-allowed data-[locked]:hover:bg-transparent', 'group-data-[state=done]/item:text-muted-foreground group-data-[state=done]/item:line-through group-data-[state=skipped]/item:text-muted-foreground', )} > <span className="flex min-w-0 flex-1 flex-col gap-0.5"> <span className="font-medium"> {title} <span className="ml-1.5 hidden text-[11px] font-normal text-muted-foreground group-data-[optional]/item:inline"> Optional </span> </span> {description && ( <span className="text-xs font-normal text-muted-foreground no-underline"> {description} </span> )} </span> <Lock aria-hidden="true" className="hidden size-3.5 shrink-0 text-muted-foreground group-data-[locked]/item:block" /> <ChevronRight className="size-4 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover/item:opacity-100 group-data-[state=done]/item:hidden group-data-[locked]/item:hidden" /> </Checklist.ItemTrigger> </Checklist.Item> );}
export interface ChecklistPanelProps extends Omit<ChecklistRootProps, 'children' | 'title'> { title?: React.ReactNode; description?: React.ReactNode; /** Item title / description, read from `meta` by default. */ renderItem?: (item: ChecklistItemDefinition) => { title: React.ReactNode; description?: React.ReactNode; }; /** Shown instead of the panel once dismissed. */ reopenLabel?: React.ReactNode; children?: React.ReactNode;}
const defaultRenderItem = (item: ChecklistItemDefinition) => ({ title: (item.meta?.title as React.ReactNode) ?? item.id, description: item.meta?.description as React.ReactNode,});
/** Items, grouped under their `section` titles when the checklist declares sections. */function ChecklistSections({ checklist, renderItem,}: { checklist: ChecklistInstance; renderItem: NonNullable<ChecklistPanelProps['renderItem']>;}) { const sections = useStoreSelector(checklist, (s) => s.sections); const items = checklist.getItems(); if (sections.length === 0) { return ( <ChecklistItems> {items.map((item) => ( <ChecklistRow key={item.id} value={item.id} {...renderItem(item)} /> ))} </ChecklistItems> ); } const loose = items.filter((item) => !item.section); return ( <div className="flex flex-col gap-3"> {sections.map((section) => ( <section key={section.id} aria-label={section.title ?? section.id} className="flex flex-col gap-1" > <p className="flex items-baseline justify-between text-xs font-medium text-muted-foreground"> <span>{section.title ?? section.id}</span> <span className="tabular-nums"> {section.completed}/{section.total} </span> </p> <ChecklistItems> {items .filter((item) => item.section === section.id) .map((item) => ( <ChecklistRow key={item.id} value={item.id} {...renderItem(item)} /> ))} </ChecklistItems> </section> ))} {loose.length > 0 && ( <ChecklistItems> {loose.map((item) => ( <ChecklistRow key={item.id} value={item.id} {...renderItem(item)} /> ))} </ChecklistItems> )} </div> );}
/** A complete onboarding checklist card, with a "Show checklist" button once dismissed. */function ChecklistPanel({ checklist, title = 'Getting started', description, renderItem = defaultRenderItem, reopenLabel = 'Show checklist', className, children, ...props}: ChecklistPanelProps) { const dismissed = useStoreSelector(checklist as ChecklistInstance, (s) => s.dismissed); const titleId = `checklist-${checklist.id}-title`; if (dismissed) { return ( <Button variant="outline" size="sm" onClick={() => checklist.restore()}> {reopenLabel} </Button> ); } return ( <ChecklistCard checklist={checklist} aria-labelledby={titleId} className={className} {...props}> <ChecklistHeader title={title} description={description} titleId={titleId} /> <ChecklistProgressBar /> <ChecklistSections checklist={checklist} renderItem={renderItem} /> {children} </ChecklistCard> );}
export { ChecklistCard, ChecklistHeader, ChecklistItems, ChecklistPanel, ChecklistProgressBar, ChecklistRow,};