Onboarding checklist
Guide a new workspace through setup, one step at a time.
pnpm dlx shadcn@latest add @uiarc/onboarding-checklistLive · keyboard ready
Set up Northwind
1 of 4 done
Priya and Jonas are waiting.
- 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.
- 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.
Installation
Add Onboarding checklist with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/onboarding-checklistAdds the component and its local dependencies, and installs motion, lucide-react. First time? Add the @uiarc registry to components.json, or use the full URL:
example.tsx
import { OnboardingChecklist } from "@/components/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" }, ]} /> );}OnboardingChecklist
A getting-started card with a progress ring, expandable steps with actions, and a folding completed group.
PropTypeDefaultDescription
titleRequiredstring–Card title while steps remain.stepsRequired{ 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.doneTitlestring"You’re all set"Title once every step is done.defaultCompletedstring[][]Step ids that start completed.onCompletedChange(completed: string[]) => void–Called with completed ids in step order whenever they change.defaultHiddenbooleanfalseStarts with the body collapsed.onHiddenChange(hidden: boolean) => void–Called when the Hide or Show toggle is used.classNamestring–Class on the card.- ArrowDownorArrowUp
- Moves between step titles.
- HomeorEnd
- Jumps to the first or last step title.
- EnterorSpace
- Expands a step, toggles its checkbox, or runs its action.
- 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.
- 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.
- 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.
- 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
Give your coding assistant the Markdown reference instead of screenshots.
- 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.
The full library index for assistants is at /llms.txt.
Undo toastProComponentArchive or delete rows with a second chance: the gap closes, a countdown toast merges repeat actions, and Undo or ⌘Z puts every row back exactly where it was.
Wallet stackProComponentFan a stack of cards and lift one out to see its activity.
Liquid tab barProComponentTabs with a lens selection that slides between them, swaps labels cleanly, and fills in icons as it passes.