Skip to content
awesome-tour

Type to search every page.

    DChecklistContents

    Checklist

    A styled onboarding checklist — progress, completion states and a dismiss/restore flow.

    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>
    );
    }

    Installation

    Terminal window
    pnpm dlx shadcn@latest add @awesome-tour/checklist
    Terminal window
    npx shadcn@latest add @awesome-tour/checklist

    Usage

    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

    components/awesome-tour/checklist.tsx
    '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,
    };