OnboardingChecklist

A getting-started checklist with a progress ring that opens the next step, runs its action, and folds finished steps away.

When to use

• A short, one-time setup of three to eight steps for a new account or workspace.
• Steps that can be completed from the list itself (copy a connection string, create a preview) or checked off by hand.
• Not for a strict ordered flow with its own screens: use Stepper with your form. Not for a single reminder: use Alert.

Usage

import { OnboardingChecklist } from "@/components/iris/onboarding-checklist/onboarding-checklist";

h(OnboardingChecklist, {
  title: "Get started with CapyDB",
  doneTitle: "Your project is ready",
  defaultCompleted: ["project"],
  steps: [
    { id: "project", title: "Create a project" },
    {
      id: "preview",
      title: "Create a preview database",
      description: "A clone of 256 MB is ready in about 10 s.",
      actionLabel: "Create preview",
      onAction: () => api.createPreview(),
    },
    { id: "invite", title: "Invite your team" },
  ],
  onCompletedChange: (ids) => saveProgress(ids),
});

Props

Prop	Type	Default	Description
title	string	—	Required. Heading while steps remain.
doneTitle	string	"You’re all set"	Heading once every step is done.
steps	OnboardingStep[]	—	Required. { id, title, description?, actionLabel?, onAction? }. Without actionLabel a step is checked off by hand.
defaultCompleted	string[]	[]	Step ids already done.
onCompletedChange	(completed: string[]) => void	—	Called with the done ids after every change.
defaultHidden	boolean	false	Start with the list folded under its header.
onHiddenChange	(hidden: boolean) => void	—	Called when Hide / Show is toggled.
className	string	—	Extra class.

onAction may return a promise: resolve to check the step off, or throw an Error to keep it open and show its message.

Notes

• State is uncontrolled after mount; persist it with onCompletedChange and feed it back through defaultCompleted.
• Checks are aria-checked toggles; the next open step takes focus after one finishes, and pending actions set aria-busy.
• Finished steps strike through and collapse into a "{n} completed" row that can be reopened. Reduced motion removes the folding animation.
• Reads --accent, --on-accent, --surface, --hover, --line, --line-strong, --ink, --ink-2, --ink-3, --red.