What is an onboarding checklist?
An onboarding checklist is a persistent, visible list of tasks that guides new users from signup to their first meaningful outcome inside your product. Unlike product tours that walk users through a fixed sequence, checklists hand control to the user. They choose what to tackle and when.
That distinction matters more than it sounds. As of April 2026, the average onboarding checklist completion rate across 188 SaaS companies is just 19.2%, with a median of 10.1% (Userpilot, 2025). Most checklists fail because they're built as feature dumps, not as guided paths to value.
npm install @tour-kit/checklists @tour-kit/coreTry the live checklist demo or browse the API reference.
Definition
An onboarding checklist is a UI component that breaks user activation into discrete, completable tasks displayed as a visible progress tracker within the application. Each task maps to a specific action (completing a profile, creating a first project) and persists across sessions so users can return where they left off. The pattern draws on the Zeigarnik effect: people remember incomplete tasks better than completed ones, making a partially-checked list a strong motivator to keep going.
The W3C WAI-ARIA Authoring Practices specify that progress indicators should use role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax attributes. Most onboarding tools skip this entirely.
How onboarding checklists work
An onboarding checklist separates task configuration from visual rendering, letting developers define completion logic, dependency chains, and persistence strategy independently of the UI layer. This separation is what makes headless implementations possible. The architecture breaks into three layers.
Configuration defines the tasks and their dependencies. In code, that looks like a typed array of task objects with IDs, labels, and optional dependency chains.
State tracks completion and progress. Which tasks are done? Which are locked behind unfinished prerequisites? Good implementations persist this to localStorage or a backend so returning users don't start over.
Rendering is the UI layer. A headless checklist gives you the logic without dictating visuals. You bring the markup.
| Aspect | Onboarding checklist | Product tour |
|---|---|---|
| User control | Self-directed, any order | Sequential, guided |
| Pacing | User's own pace, across sessions | Product-controlled, single session |
| Visibility | Persistent, collapsible panel | Temporary overlay |
| Completion model | Task-based with dependencies | Step-based, linear |
| Best for | Multi-session activation goals | Single-feature discovery |
They're complementary, not competing. Users who complete a checklist item and then trigger a contextual tour are 21% more likely to finish that tour (Storylane, 2025).
Onboarding checklist examples
A working onboarding checklist in React needs about 40 lines of code when you use a headless library that handles state management, dependency resolution, and progress calculation for you. Here's a minimal example using Tour Kit's ChecklistHeadless component with full accessibility markup.
// src/components/OnboardingChecklist.tsx
import {
ChecklistProvider,
ChecklistHeadless,
type ChecklistConfig,
} from '@tour-kit/checklists'
const onboarding: ChecklistConfig = {
id: 'getting-started',
title: 'Get started',
tasks: [
{ id: 'profile', title: 'Complete your profile', manualComplete: true },
{ id: 'project', title: 'Create a project', dependsOn: ['profile'] },
{
id: 'invite',
title: 'Invite a teammate',
dependsOn: ['project'],
action: { type: 'navigate', url: '/settings/team' },
},
],
onComplete: () => console.log('Onboarding finished'),
}
export function OnboardingChecklist() {
return (
<ChecklistProvider checklists={[onboarding]}>
<ChecklistHeadless checklistId="getting-started">
{({ tasks, progress, completeTask }) => (
<div role="region" aria-label="Onboarding progress">
<div
role="progressbar"
aria-valuenow={progress.percentage}
aria-valuemin={0}
aria-valuemax={100}
aria-label={`${progress.completed} of ${progress.total} tasks done`}
>
<div style={{ width: `${progress.percentage}%` }} />
</div>
<ul>
{tasks.map((task) => (
<li key={task.config.id}>
<button
onClick={() => completeTask(task.config.id)}
disabled={task.locked}
aria-disabled={task.locked}
>
{task.completed ? '✓' : '○'} {task.config.title}
</button>
</li>
))}
</ul>
</div>
)}
</ChecklistHeadless>
</ChecklistProvider>
)
}That's 40 lines. The dependsOn array locks "Create a project" until "Complete your profile" is done. The role="progressbar" and aria-valuenow attributes make the progress bar accessible to screen readers, following MDN's progressbar role guidance.
Why onboarding checklists matter for SaaS
Completion rates tell a stark story. Across 188 SaaS companies, FinTech apps average 24.5% while MarTech scrapes by at 12.5% (Userpilot, 2025). Company size matters too. Startups at $1-5M revenue hit 27.1%. Scale to $10-50M and it drops to 15%.
Why? Smaller teams keep checklists tight — 3-5 focused tasks. Larger teams stuff in 10+ items because every PM wants their feature represented, and the checklist becomes a miniature product roadmap nobody asked for. Smashing Magazine's onboarding research puts it plainly: people hold five to seven items in working memory. Go past that and completion craters.
Three design principles that actually move the needle:
- Keep it to 4-7 tasks. Aligns with Miller's Law. Pre-credit tasks the user already completed (like email verification) to create momentum via the Zeigarnik effect.
- Make it collapsible, not modal. Self-serve guidance that users trigger voluntarily sees 123% higher completion than auto-triggered overlays.
- Connect tasks to tours. A checklist item that triggers a contextual product tour creates a 21% completion boost. Tour Kit supports this natively with the
{ type: 'tour', tourId: 'feature-walkthrough' }action type.
Onboarding checklists in User Tour Kit
The @tour-kit/checklists package provides a headless onboarding checklist implementation with dependency resolution, progress calculation, persistence hooks, and under 5KB gzipped bundle size — no prescribed UI, so you style it with Tailwind, shadcn/ui, or plain CSS.
It handles the hard parts. Circular dependency detection with hasCircularDependency(). Automatic task locking via canCompleteTask(). And cross-session state recovery through useChecklistPersistence() so users pick up where they left off.
One honest limitation: Tour Kit doesn't have a visual builder. You configure checklists in TypeScript, which means your team needs React developers. If you want drag-and-drop creation without code, tools like Userpilot or Appcues are better fits. But if you want full control over the markup and behavior, a headless approach gives you that.
Install and start building:
npm install @tour-kit/checklists @tour-kit/coreBrowse the checklist documentation, explore the GitHub repo, or check the full API reference.
FAQ
What is the difference between an onboarding checklist and a product tour?
An onboarding checklist is a persistent task list that users complete at their own pace across sessions. A product tour is a sequential walkthrough that runs in a single session. Checklists give users autonomy over ordering. As of April 2026, combining both patterns increases tour completion by 21%.
What is a good onboarding checklist completion rate?
The average across 188 SaaS companies is 19.2%, with a median of 10.1% (Userpilot, 2025). FinTech leads at 24.5%. Above 25% puts you in the top quartile. The biggest lever: reducing checklist length to 4-7 tasks mapped to activation milestones.
How many items should an onboarding checklist have?
An onboarding checklist should contain 4-7 items, aligning with Miller's Law and the 5-7 item limit of working memory (Smashing Magazine, 2023). Pre-credit tasks the user already completed to create momentum without adding cognitive load.
How do you make an onboarding checklist accessible?
Use role="progressbar" with aria-valuenow on the progress indicator. Add keyboard focus management and aria-disabled on locked tasks. Announce completions via aria-live="polite". Tour Kit includes these ARIA attributes by default.
Related articles
What is a hotspot? In-app guidance element explained
Learn what a hotspot is in onboarding UX. Covers definition, accessibility, code examples, and when to use hotspots vs tooltips in your React app.
Read article
What is a product tour? (definition, types, and examples)
Learn what a product tour is, how it works technically, and when to use each type. Covers tooltips, hotspots, modals, and walkthroughs with code examples.
Read article
What is a slideout? In-app messaging element explained
Learn what a slideout is, how it differs from modals and drawers, and when to use slideout panels for in-app messaging and onboarding.
Read article
What is a tooltip? (and when to use tooltips in product tours)
A developer's definition of tooltips covering ARIA patterns, WCAG 1.4.13, the four tooltip types, and how tooltips work inside product tours.
Read article