# Onboarding checklist

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

- Type: Component (feedback)
- Access: Free, open source
- Page: https://ui.xzero.co.uk/components/onboarding-checklist
- Markdown: https://ui.xzero.co.uk/components/onboarding-checklist/markdown
- Registry item: https://mcp.xzero.co.uk/r/onboarding-checklist.json
- Source file: `registry/components/onboarding-checklist/onboarding-checklist.tsx`
- Dependencies: motion, lucide-react
- Keywords: onboarding, checklist, getting started, react onboarding checklist, getting started checklist, setup checklist, user onboarding, progress checklist, task list onboarding

## 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.

## Installation

Register both Xzero UI namespaces in your project's components.json:

```json
{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}
```

```bash
npx shadcn@4.23.0 add @xzero-ui/onboarding-checklist
```

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

## Usage

```tsx
import { OnboardingChecklist } from "@/components/xzero/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.

## Related

- [Stepper](https://ui.xzero.co.uk/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.
- [Progress](https://ui.xzero.co.uk/components/progress/markdown): Show how much of a known task is complete.
- [Accordion](https://ui.xzero.co.uk/components/accordion/markdown): Progressively reveal supporting information in place.
- [Checkbox](https://ui.xzero.co.uk/components/checkbox/markdown): A binary choice with a precise, legible state.

## Also in progress

- [Skeleton](https://ui.xzero.co.uk/components/skeleton/markdown): Reserve space while content is still loading.
- [Countdown](https://ui.xzero.co.uk/components/countdown/markdown): A launch countdown with rolling digits that morphs into a live state at zero.
- [Usage meter](https://ui.xzero.co.uk/components/usage-meter/markdown): 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://ui.xzero.co.uk/llms.txt