@tour-kit/checklists

Onboarding checklists with task dependencies, progress tracking, persistence, and optional tour integration for React apps

LLM Context File

Working with an AI assistant? Download the context file for @tour-kit/checklists and paste it into your conversation for accurate code generation.

Interactive checklists with task dependencies, progress tracking, and action triggers. Perfect for onboarding flows, feature adoption, and guided user journeys.

Why Checklists?

Checklists provide a structured way to guide users through multi-step processes:

Progressive disclosure - Break complex workflows into manageable tasks
Visual progress - Users see how far they've come and what remains
Smart dependencies - Tasks unlock only when prerequisites are met
Action triggers - Tasks can navigate, launch tours, or execute custom logic
Persistent state - Track completion across sessions

Use checklists for:

Onboarding new users through setup steps
Feature adoption campaigns
Account setup and configuration
Multi-step workflows with dependencies
Progress tracking toward goals

Use tours instead when:

You need sequential, guided walkthroughs
Steps require focused, modal-like attention
The flow is linear without branching

Installation

pnpm add @tour-kit/checklists

npm install @tour-kit/checklists

yarn add @tour-kit/checklists

Quick Start

import { ChecklistProvider, Checklist, ChecklistTask } from '@tour-kit/checklists';

const onboardingChecklist = {
  id: 'onboarding',
  title: 'Get Started',
  description: 'Complete these steps to get the most out of our app',
  tasks: [
    {
      id: 'create-account',
      title: 'Create your account',
      description: 'Sign up and verify your email',
    },
    {
      id: 'add-profile',
      title: 'Add profile details',
      description: 'Tell us about yourself',
      dependsOn: ['create-account'], // Locked until account created
    },
    {
      id: 'first-project',
      title: 'Create your first project',
      description: 'Start building something amazing',
      dependsOn: ['add-profile'],
      action: { type: 'navigate', url: '/projects/new' },
    },
  ],
};

function App() {
  return (
    <ChecklistProvider checklists={[onboardingChecklist]}>
      <Checklist checklistId="onboarding">
        <ChecklistTask taskId="create-account" />
        <ChecklistTask taskId="add-profile" />
        <ChecklistTask taskId="first-project" />
      </Checklist>

      <YourAppContent />
    </ChecklistProvider>
  );
}

Architecture

The checklists package uses a provider/consumer pattern with powerful dependency resolution:

ChecklistProvider
├── Context (state management)
│   ├── checklists Map<id, ChecklistState>
│   ├── Dependency resolver
│   └── Action executor
├── Components
│   ├── Checklist (styled container)
│   ├── ChecklistTask (individual task)
│   ├── ChecklistProgress (progress bar)
│   ├── ChecklistLauncher (toggle button)
│   └── ChecklistPanel (floating panel)
└── Hooks
    ├── useChecklist(id) (checklist state)
    ├── useTask(id, taskId) (task state)
    ├── useChecklistPersistence() (storage)
    └── useChecklistsProgress() (multi-checklist)

State Management

In-memory state - Managed via React context with useReducer
Dependency resolution - Automatic task locking based on dependsOn
Circular detection - Throws error if circular dependencies detected
Persistence - Optional localStorage/sessionStorage integration

Key Concepts

Concept	Description
Task	An individual item that can be completed
Dependency	Tasks can depend on other tasks via `dependsOn`
Locked	Task is disabled because dependencies aren't met
Visible	Task passes its `when` condition
Action	What happens when task is clicked (navigate, tour, callback)
Progress	Calculated as completed / total visible tasks

Features

Task Dependencies

Build complex workflows with automatic dependency management:

const tasks = [
  { id: 'step1', title: 'First step' },
  { id: 'step2', title: 'Second step', dependsOn: ['step1'] },
  { id: 'step3', title: 'Final step', dependsOn: ['step1', 'step2'] },
];

Circular dependencies will throw an error: "Circular dependency detected in checklist"

Action Triggers

Tasks can trigger different actions when clicked:

const tasks = [
  {
    id: 'navigate-task',
    title: 'View dashboard',
    action: { type: 'navigate', url: '/dashboard' },
  },
  {
    id: 'tour-task',
    title: 'Learn the basics',
    action: { type: 'tour', tourId: 'intro-tour' },
  },
  {
    id: 'callback-task',
    title: 'Custom action',
    action: {
      type: 'callback',
      handler: async () => {
        await api.doSomething();
      }
    },
  },
];

Conditional Visibility

Show/hide tasks based on context:

const tasks = [
  {
    id: 'premium-task',
    title: 'Unlock premium features',
    when: (context) => context.user.plan === 'free',
  },
  {
    id: 'admin-task',
    title: 'Configure team settings',
    when: (context) => context.user.role === 'admin',
  },
];

Auto-Completion

Tasks can auto-complete based on conditions:

const tasks = [
  {
    id: 'take-tour',
    title: 'Complete the intro tour',
    completedWhen: { tourCompleted: 'intro-tour' },
  },
  {
    id: 'custom-condition',
    title: 'Reach 10 projects',
    completedWhen: {
      custom: (context) => context.data.projectCount >= 10,
    },
  },
];

Programmatic Control

Full control via hooks:

const { completeTask, uncompleteTask, executeAction, progress } = useChecklist('onboarding');
const { isCompleted, isLocked, toggle } = useTask('onboarding', 'step1');

Headless Mode

Build completely custom UIs with headless components:

import { ChecklistHeadless } from '@tour-kit/checklists/headless';

<ChecklistHeadless checklistId="onboarding">
  {({ checklist, visibleTasks, progress, completeTask }) => (
    // Your custom UI
    <div>
      <h2>{checklist.config.title}</h2>
      <progress value={progress.completed} max={progress.total} />
      {visibleTasks.map((task) => (
        <button
          key={task.config.id}
          onClick={() => completeTask(task.config.id)}
          disabled={task.locked}
        >
          {task.completed ? '✓' : '○'} {task.config.title}
        </button>
      ))}
    </div>
  )}
</ChecklistHeadless>

Bundle Size

Package	Gzipped
@tour-kit/checklists	< 8KB

Package Contents

Providers

ChecklistProvider - Configure and provide checklist state

Hooks

useChecklist, useTask - Programmatic control and state access

Components

Checklist, ChecklistTask, ChecklistProgress - Pre-styled components

Headless

Build custom checklist UI with render props

Utilities

Factories, dependency resolution, progress calculation

Types

TypeScript type definitions and interfaces

Complete Example

import {
  ChecklistProvider,
  ChecklistPanel,
  ChecklistLauncher,
  Checklist,
  ChecklistTask,
  ChecklistProgress,
  useChecklist,
} from '@tour-kit/checklists';

const setupChecklist = {
  id: 'setup',
  title: 'Account Setup',
  description: 'Get your account ready in 3 steps',
  dismissible: true,
  hideOnComplete: true,
  tasks: [
    {
      id: 'verify-email',
      title: 'Verify your email',
      description: 'Check your inbox for verification link',
      icon: '📧',
    },
    {
      id: 'add-payment',
      title: 'Add payment method',
      description: 'Add a credit card to enable premium features',
      icon: '💳',
      dependsOn: ['verify-email'],
      action: { type: 'navigate', url: '/settings/billing' },
    },
    {
      id: 'invite-team',
      title: 'Invite team members',
      description: 'Collaborate with your team',
      icon: '👥',
      dependsOn: ['verify-email'],
      action: { type: 'modal', modalId: 'invite-modal' },
    },
  ],
  onComplete: () => {
    console.log('Setup complete!');
    analytics.track('setup_completed');
  },
};

function App() {
  return (
    <ChecklistProvider checklists={[setupChecklist]}>
      {/* Floating panel with launcher */}
      <ChecklistPanel checklistId="setup">
        <ChecklistProgress />
        <Checklist>
          <ChecklistTask taskId="verify-email" />
          <ChecklistTask taskId="add-payment" />
          <ChecklistTask taskId="invite-team" />
        </Checklist>
      </ChecklistPanel>

      <ChecklistLauncher checklistId="setup" />

      <YourAppContent />
    </ChecklistProvider>
  );
}

function ChecklistControls() {
  const { progress, isComplete, reset } = useChecklist('setup');

  return (
    <div>
      <p>{progress.completed} of {progress.total} completed</p>
      {isComplete && (
        <button onClick={reset}>Start over</button>
      )}
    </div>
  );
}

Accessibility

All checklist components are built with accessibility in mind:

ARIA attributes - Proper roles, labels, and states
Keyboard support - Full keyboard navigation
Focus management - Logical focus order
Screen readers - Descriptive labels and progress announcements

Task completion is announced to screen readers via live regions.

Tours - For sequential, guided walkthroughs
@tour-kit/core - Shared utilities used by checklists
@tour-kit/hints - For contextual, non-sequential hints