Onboarding checklist

Guide a new workspace through setup, one step at a time.

import { OnboardingChecklist } from "@/forma/arc/onboarding-checklist/onboarding-checklist";

Base

In FORMA

Liegt in kit/arc/onboarding-checklist und ist über @/forma/arc/onboarding-checklist/onboarding-checklist erreichbar.
Farbe, Ecken, Höhen, Abstände, Tiefe, Schrift und Tempo kommen aus der Richtung (core/arc-bridge.ts); Arc behält Verhalten, Tastatur und Federn.

When to use

A one-time getting-started card with three to eight loosely ordered steps.
Setup steps that run async actions, like Connect GitHub, and check off when they resolve.
Checklists people can hide and come back to, with state persisted through callbacks.

When not to use

Use stepper when the order is strict and steps map to screens.
Use multi-step-form when every step collects form input.
Use accordion for plain collapsible content without completion.

Usage

import { OnboardingChecklist } from "@/forma/arc/onboarding-checklist/onboarding-checklist";

export function GettingStarted() {
  return (
    <OnboardingChecklist
      title="Set up your workspace"
      defaultCompleted={savedIds}
      onCompletedChange={saveIds}
      steps={[
        { id: "invite", title: "Invite your team", actionLabel: "Invite", onAction: openInvite },
        { id: "connect", title: "Connect GitHub", description: "Sync issues and PRs.", actionLabel: "Connect", onAction: connectGithub },
        { id: "profile", title: "Add a profile photo" },
      ]}
    />
  );
}

API reference

OnboardingChecklist

A getting-started card with a progress ring, expandable steps with actions, and a folding completed group.

Prop	Type	Default	Description
`title` (required)	`string`	–	Card title while steps remain.
`steps` (required)	`{ id: string; title: string; description?: string; actionLabel?: string; onAction?: () => void \| Promise<void> }[]`	–	Steps in order. onAction resolving checks the step; throwing an Error keeps it open and shows the message.
`doneTitle`	`string`	`"You’re all set"`	Title once every step is done.
`defaultCompleted`	`string[]`	`[]`	Step ids that start completed.
`onCompletedChange`	`(completed: string[]) => void`	–	Called with completed ids in step order whenever they change.
`defaultHidden`	`boolean`	`false`	Starts with the body collapsed.
`onHiddenChange`	`(hidden: boolean) => void`	–	Called when the Hide or Show toggle is used.
`className`	`string`	–	Class on the card.

Keyboard interactions

Keys	Action
ArrowDown / ArrowUp	Moves between step titles.
Home / End	Jumps to the first or last step title.
Enter / Space	Expands a step, toggles its checkbox, or runs its action.

Accessibility

Each step has a role="checkbox" button with aria-checked, and a title button with aria-expanded controlling a labelled region.
The ring is role="progressbar" with aria-valuetext like "3 of 5 steps done"; progress and errors are announced via role="status" and role="alert".
When a focused step finishes, focus moves to the next step's action; leaving rows and the hidden body are inert.

Motion

Checks fill from the center and draw their tick; after 720ms the finished step folds into the completed group while the ring and count roll forward.
Rows and panels open and close on a non-overshooting spring; the title morphs to doneTitle and a tick draws in the ring at 100%.
Reduced motion removes height and scale animation and keeps short fades.

Responsive behavior

The card is a container query context; below 380px the Hide button collapses to an icon.
Step titles and checkboxes keep 40px targets, and the completed group toggle is 44px tall.

Performance

Steps are not virtualized; the component is built for short lists.
Each finished step waits 720ms on a timer before folding into the completed group.

Notes for AI

Use for a short, one-time setup of three to eight loosely ordered steps. Use stepper when the order is strict and steps map to screens.
Make onAction async and throw an Error with a readable message on failure. Persist onCompletedChange and onHiddenChange to restore state via the default props.

Also in progress

Skeleton: Reserve space while content is still loading.
Countdown: A launch countdown with rolling digits that morphs into a live state at zero.
Usage meter: Show what fills an allowance and how close it is to the limit.

Guidance for AI tools

Onboarding checklist: Guide a new workspace through setup, one step at a time. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt

ZurückUsage meter WeiterImage compare

Komponente und Text: Arc UI (MIT, uiarc.dev), angepasst für FORMA.