Source: https://monarchui.dev/components/onboarding-checklist/

Components · Workflow

# OnboardingChecklist

A first-run checklist with done steps, a progress summary, per-step actions, collapse and dismiss.

@rookcom/monarch-react/patterns

Component

## Get started

## Usage examples

### Complete

## Purpose

Guides people through setting up a product: a short list of steps, each with a done state and an optional call to action, and a summary of how far they are.

### Use when

- A new workspace or account has a handful of setup steps that unlock the product.
- Steps can be done in any order and are completed by doing the thing itself (the product ticks them from its data).
- People should be able to put the checklist away (collapse) or remove it for good (dismiss).

### Avoid when

- The steps must happen in order inside one flow: use Stepper.
- There is one thing to do: use a callout or an empty state with an action.

## Design principles

- The product owns the truth: it defines the steps, decides when each is done and persists collapse and dismiss.
- Done is shown three ways: a filled check marker, muted title, and hidden "Done" text for screen readers.
- The next step stands out (`aria-current="step"`, accent marker, tinted row) so people know where to go.
- An action belongs only to a step that is not done; done steps lose their description and action.
- Progress reuses Progress, and turns success when everything is done, with a completion message.
- Unlike Stepper, the order is a suggestion, not a sequence the component enforces.

## API reference

```tsx
import { OnboardingChecklist } from '@rookcom/monarch-react/patterns';
```

| Export | Kind | Rendering | Root class |
| --- | --- | --- | --- |
| `OnboardingChecklist` | component | client | `.mn-onboarding-checklist` |

`steps` are `{ id, title, done, description?, action? }`. `action` is any node, typically a small Button or a link.

Collapse is controlled with `collapsed` + `onCollapsedChange`, or uncontrolled with `defaultCollapsed`; `collapsible={false}` removes the toggle.

The dismiss button shows only when `onDismiss` is given; the product hides the checklist and remembers it.

The ref is the root `<section>`, labelled by the title; other attributes pass through.

Generated from the TypeScript declarations of `packages/react/src/components/workflow/onboarding-checklist`.

## Properties

### `OnboardingChecklist`

A first-run checklist: steps with a done state and an optional call to action, a progress summary, and collapse and dismiss controls. The product defines the steps, decides when each is done and persists collapse and dismiss.

| Prop | Type | Description |
| --- | --- | --- |
| `steps` required | `readonly OnboardingStep[]` |  |
| `title` required | `ReactNode` | Heading of the checklist, e.g. "Get started". |
| `children` | `ReactNode` |  |
| `className` | `string` |  |
| `collapsed` | `boolean` | Steps hidden (controlled). The product persists it. |
| `collapsible` | `boolean` | Show a toggle that hides the steps. Default true. |
| `completeContent` | `ReactNode` | Shown when every step is done. Default `messages.complete`. |
| `defaultCollapsed` | `boolean` | Steps hidden at first render (uncontrolled). |
| `description` | `ReactNode` | Text under the heading. |
| `headingLevel` | `3 \| 4 \| 6 \| 2 \| 5` | Heading level of the title. Default 2. |
| `id` | `string` |  |
| `messages` | `Partial<OnboardingChecklistMessages>` | Override labels. |
| `onCollapsedChange` | `((collapsed: boolean) => void)` |  |
| `onDismiss` | `(() => void)` | Called by the dismiss button, which shows only when this is set. The product persists it. |

## Variants

| Prop | Values | Description |
| --- | --- | --- |
| `collapsible` | `'true'``'false'` | Show the toggle that hides the steps (default). The title and progress stay visible. |
| `headingLevel` | `'2'``'3'``'4'``'5'``'6'` | Heading level of the title, to fit the page outline. Default 2. |

## States

| State | Exposed as | Behaviour |
| --- | --- | --- |
| Step done | `data-done` | Filled success marker with a check; muted title. |
| Current step | `data-current, aria-current="step"` | The first step not done: accent marker and tinted row. |
| Collapsed | `data-collapsed, aria-expanded="false"` | Only the header and progress show. |
| Complete | `data-complete` | Every step is done: success progress and the completion message (`completeContent`). |

## Interaction behaviour

- The toggle shows and hides the steps; the chevron turns to show the state.
- Dismiss calls `onDismiss`; nothing is hidden until the product stops rendering the checklist.
- Step actions are the product’s own buttons or links and behave as they normally do.
- When the product marks a step done, its row updates and the next step becomes current.

## Keyboard support

| Keys | Action |
| --- | --- |
| Tab | Moves to the toggle, the dismiss button, then each step’s action. |
| Enter / Space | Activates the toggle, dismiss or a step action. |

## Accessibility

Role

region (section) labelled by the title; an ordered list of steps

Accessible name

The

title

.

- The toggle is a button named by the title with `aria-expanded` and `aria-controls`.
- The progress bar is named "Setup progress" and reads "2 of 4 done".
- Each step title is followed by hidden ", Done" or ", Not done" text; the current step has `aria-current="step"`.
- The dismiss button is named "Dismiss checklist".
- Verified with axe in jsdom and in Chromium, Firefox and WebKit on /components/onboarding-checklist.

## Responsive behaviour

- Step actions sit at the end of the row on wider screens and wrap under the text on narrow ones, aligned with the title.
- The header wraps; the progress bar always takes the full width. Works at 320px.

## Theme support

- Colours are Monarch semantic tokens only, so light, dark and more-contrast themes apply automatically.
- Done markers use `--mn-color-success-solid` and `--mn-color-success-on-solid`; the current step uses `--mn-color-accent-strong`.
- Reduced motion removes the toggle transition. Forced colours outline done markers with `Highlight`.

## Do and don't

### Do

- Keep it short: three to six steps that matter for getting value.
- Tick steps from real data (the thing was done), not from clicking the action.
- Persist collapse and dismiss per person, and offer a way back (for example in Help).

### Don't

- Do not use it for a strict sequence or a form split into pages: use Stepper.
- Do not show it to people who have finished setup; hide it once dismissed or complete.
- Do not put several actions in one step.

## Related components

- [Stepper](https://monarchui.dev/components/stepper/): Steps in a fixed order inside one flow.
- [Progress](https://monarchui.dev/components/progress-bar/): The progress summary, on its own.
- [EmptyState](https://monarchui.dev/components/empty-state/): A single first action on an empty screen.

## Dependencies

| Kind | Depends on |
| --- | --- |
| npm packages | `react` |
| Monarch components | [Button](https://monarchui.dev/components/button/), [Progress](https://monarchui.dev/components/progress-bar/) |

## Testing coverage

- Steps, done state, progress value text and the current step render; actions are the product’s nodes; axe passes.
- Done steps hide their description and action.
- Collapse uncontrolled (click and keyboard) and controlled; `collapsible={false}` removes the toggle; progress stays visible.
- Dismiss shows only with `onDismiss` and calls it.
- Complete state with success progress and custom content; empty list; heading level; translated messages; server rendering.

| Check | Covered |
| --- | --- |
| Axe in jsdom | Yes |
| Server rendering | Yes |
| Browser suites | Visual baselines: /__gallery/onboarding-checklist; Cross-browser axe: /components/onboarding-checklist |

Tests: `packages/react/src/components/workflow/onboarding-checklist`

## All example code

### Get started

```tsx
import { useState } from 'react';
import { Button } from '@rookcom/monarch-react';
import { OnboardingChecklist, type OnboardingStep } from '@rookcom/monarch-react/patterns';

function ChecklistDemo() {
  const [done, setDone] = useState<Record<string, boolean>>({ profile: true });
  const [collapsed, setCollapsed] = useState(false);
  const [dismissed, setDismissed] = useState(false);
  const finish = (id: string) => setDone((d) => ({ ...d, [id]: true }));
  const steps: OnboardingStep[] = [
    { id: 'profile', title: 'Complete your profile', done: !!done.profile },
    {
      id: 'invite',
      title: 'Invite your team',
      description: 'Work is easier to share with the people you work with.',
      done: !!done.invite,
      action: (
        <Button size="sm" onClick={() => finish('invite')}>
          Invite people
        </Button>
      ),
    },
    {
      id: 'project',
      title: 'Create your first project',
      description: 'Start from a template or a blank project.',
      done: !!done.project,
      action: (
        <Button size="sm" variant="secondary" onClick={() => finish('project')}>
          New project
        </Button>
      ),
    },
    {
      id: 'notifications',
      title: 'Choose your notifications',
      done: !!done.notifications,
      action: (
        <Button size="sm" variant="ghost" onClick={() => finish('notifications')}>
          Open settings
        </Button>
      ),
    },
  ];
  if (dismissed)
    return (
      <Button variant="secondary" onClick={() => setDismissed(false)}>
        Show the checklist again
      </Button>
    );
  return (
    <OnboardingChecklist
      style={{ width: '100%', maxWidth: 560 }}
      title="Get started"
      description="A few steps to set up your workspace."
      steps={steps}
      collapsed={collapsed}
      onCollapsedChange={setCollapsed}
      onDismiss={() => setDismissed(true)}
    />
  );
}

<ChecklistDemo />
```

### Complete

```tsx
import { OnboardingChecklist } from '@rookcom/monarch-react/patterns';

<OnboardingChecklist
  style={{ width: '100%', maxWidth: 560 }}
  title="Set up billing"
  headingLevel={3}
  collapsible={false}
  steps={[
    { id: 'plan', title: 'Choose a plan', done: true },
    { id: 'payment', title: 'Add a payment method', done: true },
    { id: 'invoice', title: 'Set invoice details', done: true },
  ]}
  completeContent="Billing is ready. You can change it any time in Settings."
/>
```