add-onboarding-checklist

Add an onboarding checklist with @tour-kit/checklists

Use @tour-kit/checklists when the user wants a persistent task list that tracks user progress — e.g. "Complete your profile → Invite a teammate → Create your first project". Supports task dependencies (locked tasks until prereqs are done), progress percentages, and integration with tours.

Install

pnpm add @tour-kit/checklists @tour-kit/core

Minimal working example

'use client'
import {
  ChecklistProvider,
  ChecklistPanel,
  createChecklist,
} from '@tour-kit/checklists'

const onboarding = createChecklist({
  id: 'onboarding',
  title: 'Get started with Acme',
  tasks: [
    {
      id: 'profile',
      title: 'Complete your profile',
      action: { type: 'navigate', url: '/settings/profile' },
    },
    {
      id: 'invite',
      title: 'Invite a teammate',
      dependsOn: ['profile'],
      action: { type: 'navigate', url: '/team' },
    },
    {
      id: 'project',
      title: 'Create your first project',
      action: { type: 'tour', tourId: 'project-creation-tour' },
    },
  ],
})

export function App() {
  return (
    <ChecklistProvider checklists={[onboarding]}>
      <ChecklistPanel checklistId="onboarding" />
      {/* rest of app */}
    </ChecklistProvider>
  )
}

The panel shows progress (e.g. "1 of 3 complete"), locks tasks until dependencies are met, and persists completion state in localStorage.

Task action types

• { type: 'navigate', url } — clicking the task pushes a route
• { type: 'callback', handler } — call an arbitrary function
• { type: 'tour', tourId } — launch a @tour-kit/react tour (requires <TourProvider> in the tree)

Common follow-ups

Complete tasks programmatically (event-based)

import { useChecklist } from '@tour-kit/checklists'

function ProfileForm() {
  const { completeTask } = useChecklist('onboarding')
  return <form onSubmit={() => completeTask('profile')}>{/* ... */}</form>
}

Headless rendering (custom UI)

Use <ChecklistHeadless> to get state via render props and build your own panel.

Persistence

Default storage is localStorage. Pass a custom storageAdapter to the provider for cookies, IndexedDB, or server-side persistence.

Gotchas

• Circular dependencies in dependsOn will throw at provider mount. Use hasCircularDependency() from @tour-kit/checklists if building checklists dynamically.
• Locked tasks count toward total. A 5-task checklist with 3 locked still shows "Complete X/5".
• Next.js App Router: provider is client-only — mark its parent file 'use client'.

Reference

• Docs: https://usertourkit.com/docs/checklists
• npm: https://www.npmjs.com/package/@tour-kit/checklists