VibeWeek
Home/Grow/Onboarding Checklist & Setup Progress UI: Chat Prompts

Onboarding Checklist & Setup Progress UI: Chat Prompts

⬅️ Back to 6. Grow

A onboarding checklist is a persistent, in-product widget that lists the 4-7 things a new user should do to get value from the product, tracks their progress, and disappears once they've finished. It sits inside the dashboard or as a floating panel; it doesn't interrupt the user (unlike modals or tours); it auto-marks items complete as the user actually does them in the product.

This is distinct from a product tour (multi-step tooltip walkthrough) and an onboarding email sequence (out-of-product nudges). Checklists work for users who are already in the product and need orientation on what to do next without being interrupted. They lift activation rates by 20-40% in measured A/B tests when implemented well.

This is the chat-prompt playbook for shipping an onboarding checklist that doesn't get ignored, doesn't break when product changes, and graduates users out gracefully.

When You Need a Checklist

Use a checklist when:

  • New user has 4-8 distinct steps to reach activation
  • Product complexity means "just start" doesn't work
  • Steps can be detected programmatically (you can mark them complete from real events)
  • You want a persistent guide, not an interrupt

Don't use a checklist when:

  • Product activates in 1 step (just sign up + see value)
  • Steps are time-sensitive / sequential (use a wizard instead — see Multi-Step Forms / Wizards)
  • User can't reasonably progress through steps in their first session

Picking the Steps

The hardest part. Wrong checklist = wasted activation lift; right checklist = compounding retention.

Help me design the onboarding checklist for [product type, e.g. "team analytics dashboard"].

Constraints:
1. **5-7 items max** — fewer is better
2. Each item must correspond to a behavior that's predictive of long-term retention
3. Each item must be doable in the first session for most users (15-30 min total budget)
4. Sequence: easy → harder; but allow skipping
5. Tied to real events you can detect

Activation hypothesis: users who [insert your aha-moment, e.g. "create their first dashboard AND invite at least one teammate within 7 days"] retain at 3-4x baseline.

Working back from that activation event, propose:

1. The checklist of 5-7 items in recommended order
2. For each item: the user-facing copy, the "completed when X" event, the optional CTA button
3. Which one is the primary "aha moment" item (this should drive the headline)
4. Any items that are skippable vs required
5. What happens after all items completed: dismiss the checklist? Persist as "completed" state?

For my product context:
- [describe your product 2 sentences]
- [primary user persona]
- [current activation rate baseline if known]

Stack: Next.js + your product's existing event tracking (PostHog / Mixpanel / Segment).

Common checklist patterns by product type:

  • Analytics products: Connect your data → Create your first dashboard → Invite a teammate → Set up an alert → Share a dashboard
  • Project management: Create your first project → Add 3 tasks → Invite a teammate → Try a view → Connect an integration
  • Email tools: Verify your sending domain → Import contacts → Send your first campaign → Set up an automation → View results
  • Developer tools: Install the SDK → Send your first event → Set up a webhook → Invite a teammate → Configure environment

Data Model

I'm building the onboarding checklist data model.

Schema (Drizzle):

```sql
checklists:
  id, name, description, target_persona (free / pro / enterprise / role-based),
  active_from, active_to (nullable — null = always active),
  status (draft / active / archived),
  created_at

checklist_items:
  id, checklist_id, order_index, title, description, cta_label, cta_url,
  completion_event (string: name of event that marks complete),
  completion_rule (JSON: optional rule to evaluate against event payload),
  is_required (boolean),
  is_skippable (boolean)

user_checklist_progress:
  user_id, checklist_id, item_id, completed_at, skipped_at,
  primary_key: (user_id, checklist_id, item_id)

user_checklist_state:
  user_id, checklist_id, started_at, completed_at, dismissed_at,
  primary_key: (user_id, checklist_id)

Implement:

  1. Drizzle schema + types
  2. Function getActiveChecklistForUser(userId): returns the checklist + per-item progress for current user
  3. Function markItemComplete(userId, checklistId, itemId): writes progress; if all required items done, marks checklist complete
  4. Function dismissChecklist(userId, checklistId): user explicitly dismisses
  5. Auto-completion via event hooks: when an event matching completion_event fires, look up affected items and mark complete

Stack: Next.js + Drizzle + Postgres + your event tracking (PostHog / Segment / internal).


## The Component

Build the <OnboardingChecklist> component:

Layout:

  • Sidebar widget (default) OR floating bottom-right (more aggressive)
  • Header: "Get started with [Product]" + progress (e.g. "3 of 5 complete")
  • List of items:
    • Checkbox visual (filled when complete)
    • Title (strikethrough when complete)
    • Optional description
    • CTA button (if not yet complete)
    • Skip link (small, for skippable items)
  • Footer: "Hide for now" button + "I'm done" button (if all required complete)

Behavior:

  • Renders if user has an incomplete active checklist
  • Polling: checks for completion every 60s + on focus (in case completed via separate tab)
  • Optimistic UI: checking off a step animates immediately
  • Dismiss: hides for the session; persistent dismiss is "Hide forever"
  • Re-show: settings page lets users re-enable the checklist

Accessibility:

  • Tab order through items
  • Keyboard "Enter" on item triggers CTA
  • Focus management when items complete
  • Screen reader announces "Step X complete"

Empty state (after completion):

  • Brief celebration ("You're all set!")
  • Auto-fades over 5 seconds
  • Optional next-action ("Explore advanced features")

Stack: Next.js + Tailwind + shadcn/ui + TanStack Query.


## Auto-Detecting Completion

The thing that makes checklists feel magical: users do the action; the item checks off without them clicking "mark complete."

Implement auto-detection of step completion via event tracking.

Pattern:

  • Each checklist item has a completion_event (e.g. "dashboard.created")
  • When events fire from the user's actions, check if any active checklist items match
  • If yes, mark progress
  • Refresh the checklist UI in real-time (or on next poll/focus)

Two implementation options:

Option A (simple): On every event ingestion, run a query for matching active items.

  • Pro: simple
  • Con: high volume of events to scan (most won't match)

Option B (efficient): Index events by name; only check on each tracked event type.

  • Pro: scales
  • Con: more setup

For volume <100K events/day, Option A is fine. Use Option B past that.

Implement:

  1. Hook into your event-tracking layer (PostHog / Segment / internal)
  2. On every event, check if userId has active checklist; if so, find matching items; mark complete if found
  3. Idempotent: repeated events for already-completed items don't re-trigger anything
  4. Realtime UI updates: TanStack Query refetches on focus + every 60s; optimistic update if event was triggered from current session

Edge cases:

  • Event with conditional rule: e.g. "dashboard created with at least 3 widgets" — evaluate completion_rule against event payload
  • Event fired from another session (mobile): user signs in on web; sees the previously-completed step now checked

Stack: Next.js + Drizzle + your event tracking.


## Variation: Multiple Checklists for Different Roles

My product has different roles: admin, member, viewer. Each has a different onboarding path.

Implement role-based checklist selection:

  1. Each checklist has a target_persona field (e.g. "admin", "member", "viewer")
  2. On user load, look up user's role; select the matching checklist
  3. If user changes role mid-session, re-select checklist; preserve progress for any matching items

Edge cases:

  • Admin checklist has "invite teammates" but member doesn't see this item
  • Member checklist has "complete profile" but admin's already done it
  • A user promoted from member to admin: their already-done items count toward the new checklist where applicable

Show me:

  • The checklist selection logic
  • The per-role item mapping
  • The transition handling

Stack: Next.js + Drizzle.


## Time-Boxed Variants (Win-Back / Re-Engagement)

Checklists aren't just for new users. Used carefully, they re-engage at-risk users.

I want a re-engagement checklist for users who haven't taken key actions in 14+ days.

Pattern:

  • New checklist: "Get back on track" with 3-4 lighter items
  • Triggered when health-score drops below threshold OR last-active > 14 days
  • Less aggressive than initial onboarding; one item per session
  • After completion or 7-day window, auto-archives

Implementation:

  • Eligibility query runs daily: find users matching criteria
  • Eligible users get the re-engagement checklist enabled
  • Checklist itself works the same; just selected by different rules

Show me:

  • The eligibility cron job
  • The "primary" checklist vs "secondary" handling (don't show two at once)
  • The auto-archive after window

Stack: Next.js + Drizzle + Vercel Cron.


## Analytics: Did the Checklist Work?

Track checklist effectiveness:

Per-checklist metrics:

  • Reach: % of new users who saw it
  • Start rate: % who completed at least 1 item
  • Per-item completion rate (where do users drop off?)
  • Full completion rate
  • Time-to-complete (median + distribution)
  • Dismiss rate (gave up; not finished)
  • Activation correlation: of completers vs non-completers, what's the retention / activation lift?

Per-item metrics:

  • Click-through rate (saw → clicked CTA)
  • Completion rate after click
  • Skip rate

Implementation:

  • Track events: checklist_shown, item_clicked, item_completed, item_skipped, checklist_completed, checklist_dismissed
  • Tie events to user IDs for cohort analysis
  • A/B test variants of the checklist (different copy, different items, different ordering)

Show me a dashboard query (in your warehouse / PostHog) that surfaces:

  • Per-week new user cohort: how many saw, completed, retained vs control

Stack: PostHog / Mixpanel / your warehouse.


## A/B Testing Checklist Variants

I want to A/B test:

  • 5-item checklist vs 7-item version
  • "Invite teammate" first vs last
  • Persistent sidebar vs collapsible

Implement test variants:

  1. Each user assigned to a variant via your feature-flag system (GrowthBook / LaunchDarkly / Vercel Edge Config)
  2. Variant determines which checklist + which UI mode
  3. Track activation + retention by variant
  4. After 4 weeks of significance: pick winner

Avoid: too many concurrent tests on the same checklist (no power); testing tiny copy changes when bigger questions matter.

Stack: Next.js + your feature-flag tool.


## Common Pitfalls

**Too many items.** A 12-item checklist is intimidating. 5-7 max.

**Items not predictive of retention.** "Read our blog" doesn't drive retention; "Connect your data + invite a teammate" does. Pick items that correlate with cohort retention, not items that look thorough.

**Manual completion only.** User did the action; the checkbox doesn't update. Always auto-detect; manual fallback should exist but secondary.

**No skippable items.** A user with no team to invite can't progress. Allow skip on items that don't apply; track skip vs ignore.

**Persistent forever.** Checklist still visible 6 months later for power users who finished everything. Auto-archive after completion.

**Same checklist for every persona.** Admin needs "invite team"; member doesn't. Segment.

**No event-driven completion.** Checking items off via "I did this" buttons is fragile. Auto-detect.

**Checklist that hijacks attention.** Modal pop-up demanding attention. Use sidebar / non-blocking widget.

**Items that require leaving the product.** "Read our setup guide" — suddenly user is on docs site, never returns. Keep items in-product.

**No analytics on the checklist itself.** You don't know which items are abandoned. Track events.

**Not localized.** EN-only checklist for international users. Translate.

**Hardcoded items in code.** Adding/removing items requires a deploy. Use admin-managed config.

**Not versioned.** You change the checklist; in-flight users see partial progress weirdly. Version checklists; in-flight users finish their version.

**No way to dismiss.** User finished checklist; widget still showing because you forgot to mark complete. Add explicit "I'm done" + auto-dismiss on full completion.

**Never re-engage.** User dismissed early; no nudge if they later need orientation. Add re-engagement triggers.

**Items added late that don't credit prior usage.** Power user already does X; new checklist item "Do X" appears unchecked. Backfill — if completion event is in user's history, mark immediately.

**Triggering the checklist for users who clearly don't need it.** Migration users importing from another tool already know what they're doing. Detect "expert" users (existing API keys, prior account, large data import) and skip onboarding.

**Conflicting with onboarding tours.** Tour shows the same content; user is confused which to follow. Pick one primary onboarding mechanism; the other complements.

## See Also

- [Onboarding Tour Implementation](./onboarding-tour-implementation-chat.md) — multi-step tooltip tours (different)
- [Onboarding Email Sequence](./onboarding-email-sequence-chat.md) — out-of-product nudges
- [Onboarding Calls](./onboarding-calls-chat.md)
- [Activation Funnel](./activation-funnel-chat.md) — measuring what this checklist drives
- [Customer Health Scoring](./customer-health-scoring-chat.md) — using checklist completion as input
- [In-App Notifications](./in-app-notifications-chat.md)
- [In-Product Release Notes / What's New](./in-product-release-notes-whats-new-chat.md)
- [Tooltip & Hint Systems](./tooltip-hint-systems-chat.md)
- [Empty States, Loading & Error States](./empty-states-loading-error-states-chat.md)
- [Toast Notifications UI](./toast-notifications-ui-chat.md)
- [Microcopy & Product Copy Systems](./microcopy-product-copy-systems-chat.md)
- [Sidebar Navigation Implementation](./sidebar-navigation-implementation-chat.md)
- [Settings & Account Pages](./settings-account-pages-chat.md)
- [In-App Status Banners & System Notifications](./in-app-status-banners-system-notifications-chat.md)
- [Approval Workflows & Multi-Step Routing](./approval-workflows-multi-step-routing-chat.md)
- [Multi-Step Forms / Wizards](./multi-step-forms-wizards-chat.md)
- [Trial Countdown / Conversion UI](./trial-countdown-conversion-ui-chat.md)
- [Trial to Paid](./trial-to-paid-chat.md)
- [Reduce Churn](./reduce-churn-chat.md)
- [PostHog Setup](./posthog-setup-chat.md)
- [Customer Onboarding Playbook (LaunchWeek)](https://launchweek.dev/content/4-convert/customer-onboarding-playbook.md)
- [High-Touch Onboarding (LaunchWeek)](https://launchweek.dev/content/4-convert/high-touch-onboarding.md)
- [Activation Metric Definition (LaunchWeek)](https://launchweek.dev/content/4-convert/activation-metric-definition.md)
- [Customer Education & Training Programs (LaunchWeek)](https://launchweek.dev/content/4-convert/customer-education-training-programs.md)
- [Product Tour Providers (VibeReference)](https://viberef.dev/product-and-design/product-tour-providers.md) — Frigade / Userpilot / Appcues