Skip to content
awesome-tour

Type to search every page.

    EChecklistContents

    Checklist

    The headless onboarding checklist — items completed by tours, signals, predicates or by hand, with persistence.

    import { createChecklist, localStorageAdapter, type ChecklistSnapshot } from '@awesome-tour/core';
    export const gettingStarted = createChecklist({
    id: 'getting-started',
    persistence: localStorageAdapter<ChecklistSnapshot>({ prefix: 'checklist:' }),
    onComplete: () => confetti(),
    items: [
    { id: 'tour', tour: 'onboarding', meta: { title: 'Take the tour' } },
    { id: 'invite', signal: 'invited', meta: { title: 'Invite a teammate' } },
    { id: 'avatar', when: () => user.hasAvatar, meta: { title: 'Add a photo' } },
    { id: 'docs', meta: { title: 'Read the docs' } }, // completed by hand
    ],
    });

    Render it with the Checklist components. In React, @awesome-tour/react exports the instance type as ChecklistInstance (the Checklist name is the component namespace).

    createChecklist(options)

    Option Type Description
    id string Required. Also the persistence key.
    items readonly ChecklistItemDefinition[] Required. The tasks, in display order.
    persistence PersistenceAdapter<ChecklistSnapshot> Where to save item statuses and dismissed. Any persistence adapter.
    onComplete () => void Called when the last pending item is completed (again after a reset). Not called for a checklist that was already complete when loaded.

    ChecklistItemDefinition

    Field Type Description
    id string Required. Unique within the checklist.
    tour string | Tour A tour that completes this item when it completes (complete event, or already completed when linked). A tour id needs a connected manager (connect(manager); automatic under TourProvider).
    signal string Complete when checklist.signal(name) is called.
    when () => boolean Complete when the predicate returns true, checked on refresh() (and after loading persisted state).
    after string | string[] Items that must be done or skipped first. Until then the item is locked: startItem does nothing and Checklist.ItemTrigger is aria-disabled. Doing the thing anyway still completes it.
    optional boolean A nice-to-have: excluded from completed, total, progress and done.
    section string Groups the item (state.sections); titles come from options.sections.
    meta Record<string, unknown> Free-form data for rendering: title, description, icon…

    An item can combine several of these; any of them completes it. Items can always be completed manually with complete(id).

    Checklist instance

    Method / property Returns Description
    id string The checklist id.
    getItems() readonly ChecklistItemDefinition[] Item definitions.
    getItem(id) ChecklistItemDefinition | undefined One item.
    getState() ChecklistState Immutable snapshot.
    subscribe(listener) () => void Called on every state change. Works with useStoreSelector(checklist).
    complete(id) void Mark an item done.
    skip(id) void Mark an item skipped (counts as completed for progress).
    reset(id?) void Reset one item to pending, or every item and dismissed when called without an id.
    dismiss() void Hide the checklist (dismissed: true).
    restore() void Show it again (dismissed: false).
    signal(name) void Complete every item whose signal is name.
    refresh() void Re-evaluate the when predicates of pending items.
    connect(manager?) () => void Link items’ tour ids through a manager, following tours registered later. Returns a disconnect function. Checklist.Root does this with the provider’s manager.
    startItem(id) Promise<void> Start the item’s tour with force: true — through the manager with interrupt: true when it’s an id (throws if no manager is connected). No-op for items without a tour.
    ready() Promise<void> Resolves once persisted state has been loaded.
    destroy() void Stop listening to tours.

    Unknown item ids are ignored by complete, skip and reset.

    ChecklistState

    Field Type Description
    items Record<string, 'pending' | 'done' | 'skipped'> Status of every item.
    completed number Items done or skipped.
    total number Number of items.
    progress number completed / total, from 0 to 1.
    done boolean Every required (non-optional) item is done or skipped.
    locked Record<string, boolean> Items waiting on their after dependencies.
    next string | null The first pending, unlocked item (required ones first): what to do next.
    sections { id, title?, items, completed, total, done }[] Items grouped by section, in order of first appearance.
    dismissed boolean The user hid the checklist.
    hydrated boolean Persisted state has been loaded (true immediately without persistence).

    ChecklistSnapshot

    What is written to persistence (key: the checklist id) after every change once hydrated:

    Field Type
    items Record<string, ChecklistItemStatus>
    dismissed boolean
    updatedAt number

    Without React

    const manager = createTourManager({ tours: [onboarding] });
    const disconnect = gettingStarted.connect(manager);
    gettingStarted.subscribe(() => {
    const { completed, total } = gettingStarted.getState();
    badge.textContent = `${completed}/${total}`;
    });
    document.querySelector('#invite')!.addEventListener('click', () => gettingStarted.signal('invited'));
    window.addEventListener('focus', () => gettingStarted.refresh());

    See the checklist guide.