# Setup Checklist

> The dashboard Get started card: setup tasks with progress and actions, collapsible and dismissible, or a floating launcher.

- Type: React component (Feedback)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add setup-checklist`
- Docs: https://wingo-ui.com/components/setup-checklist

## Interaction

The card shows each setup task with a check, a progress bar and an x of y count. Click a task to expand it (one at a time): its description and action buttons slide open, and the first task still to do starts open. With onCompletedChange wired, the round check is a checkbox: click it and the tick pops in, the bar fills and the next open task expands; with markOnAction the main action marks its task done. Optional tasks carry a tag and stay out of the count. Click the header to fold the list away and again to bring it back; the x dismisses the card. When every task is done a "You're all set" panel replaces the list and the card folds itself up after a few seconds. The floating variant is a pill in the corner with the count: it opens the list in a popover, or a bottom sheet on a phone. Keyboard: Tab reaches each task, ArrowUp / ArrowDown / Home / End move between them, Enter or Space expands, Space toggles a focused check. On a phone the rows are 44px tall and the action buttons go full width.

## Installation

```bash
npx wingo-ui@latest add setup-checklist
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/setup-checklist` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/setup-checklist.tsx`

npm dependencies: `npm i motion lucide-react`

Wingo UI dependencies (installed automatically):

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Popover](https://wingo-ui.com/components/popover) ([Markdown](https://wingo-ui.com/components/popover.md))
- [Progress](https://wingo-ui.com/components/progress) ([Markdown](https://wingo-ui.com/components/progress.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useMediaQuery](https://wingo-ui.com/components/use-media-query) ([Markdown](https://wingo-ui.com/components/use-media-query.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { useState } from "react"
import { CreditCard, Palette, UserPlus } from "lucide-react"
import { SetupChecklist, type SetupChecklistItem } from "@/components/ui/setup-checklist"

const items: SetupChecklistItem[] = [
  { id: "brand", title: "Add your logo", description: "It shows on invoices and the client portal.", icon: <Palette />, action: { label: "Upload logo", href: "/settings/brand" } },
  { id: "team", title: "Invite your team", description: "Teammates get their own login and permissions.", icon: <UserPlus />, action: { label: "Invite people", href: "/settings/team" } },
  { id: "billing", title: "Connect payments", description: "Get paid by card or bank transfer.", icon: <CreditCard />, action: { label: "Connect Stripe", href: "/settings/payments" } },
]

export function DashboardSetup() {
  const [completed, setCompleted] = useState<string[]>(["brand"])
  return <SetupChecklist items={items} completed={completed} onCompletedChange={setCompleted} onDismiss={() => console.log("hide for good")} />
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `SetupChecklistItem[]` |  | The tasks: { id, title, description?, icon?, done?, action?: { label, onClick?, href? }, secondaryAction?, optional?, disabled? }. An item's done fixes its state from your data and wins over completed. |
| `completed?` | `string[]` |  | Ids of the finished tasks, when you control them. |
| `defaultCompleted?` | `string[]` |  | Finished task ids to start with, uncontrolled. Default: none. |
| `onCompletedChange?` | `(completed: string[]) => void` |  | Called with the new list of finished ids. Wiring it turns each check into a checkbox people can toggle; without it the checks only show state. |
| `active?` | `string \| null` |  | The expanded task's id, when you control it; null collapses every task. |
| `defaultActive?` | `string \| null` | `""` | The task expanded at first, uncontrolled; null starts with all collapsed. Left out: the first task not done. |
| `onActiveChange?` | `(active: string \| null) => void` |  | Called when a task expands or collapses. |
| `title?` | `ReactNode` | `"Get started"` | The heading of the card and the launcher's text. |
| `description?` | `ReactNode` | `"Finish setting up your workspace."` | One line under the title. |
| `progressLabel?` | `(done: number, total: number) => ReactNode` | `` "(done: number, total: number) => `${done} of ${total} done`" `` | The count next to the bar; a string result also names the bar for screen readers. |
| `variant?` | `"card" \| "inline" \| "floating"` | `"card"` | card is a raised panel for a dashboard; inline has no surface, for a sidebar or an existing card; floating is a pill pinned to the bottom corner (safe-area aware) that opens the list in a popover, or a bottom sheet below 768px. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Color of the checks, the bar, the main action and the launcher. Brand is opt-in. |
| `color?` | `string` | `""` | Any CSS color; replaces the tone. |
| `size?` | `"sm" \| "md"` | `"md"` | md for a dashboard card; sm is denser, for a sidebar or a popover. |
| `collapsible?` | `boolean` | `true` | Card and inline: the header folds the list away and brings it back. |
| `open?` | `boolean` |  | Card and inline: whether the list shows; floating: whether the panel is open. Controlled. |
| `defaultOpen?` | `boolean` | `true` | Card and inline: the list starts open. The floating panel always starts closed unless you control open. |
| `onOpenChange?` | `(open: boolean) => void` |  | Called when the list folds or unfolds, or the floating panel opens or closes. |
| `dismissible?` | `boolean` | `true` | An x in the header (and a Dismiss button in the done state) that hides the checklist. |
| `onDismiss?` | `() => void` |  | Called when it is dismissed; store it so the card stays gone. |
| `dismissLabel?` | `string` | `"Dismiss"` | The x button's accessible name and the done state's button text. |
| `doneTitle?` | `ReactNode` | `"You're all set"` | The heading of the done state that replaces the list. |
| `doneDescription?` | `ReactNode` | `"Every setup step is done."` | The line under the done heading. |
| `doneDelay?` | `number` | `4000` | Milliseconds after everything is done before a collapsible card folds up; 0 keeps it open. |
| `markOnAction?` | `boolean` | `false` | A click on a task's main action also marks it done (for actions that finish the task, like Connect). |
| `optionalLabel?` | `string` | `"Optional"` | The tag on optional tasks. |
| `completedLabel?` | `string` | `"Completed"` | Read by screen readers after a finished task's title. |
| `toggleLabel?` | `string` | `"Show or hide steps"` | The tooltip of the header toggle. |
| `responsive?` | `boolean` | `true` | Floating: below 768px the panel opens as a bottom sheet. |
| `classNames?` | `Partial<Record<"header" \| "title" \| "description" \| "progress" \| "list" \| "item" \| "check" \| "action" \| "done" \| "launcher" \| "panel", string>>` |  | Extra classes for the inner parts. launcher is the floating pill (swap fixed for absolute to pin it inside a container), panel the floating list. |
| `className?` | `string` |  | Extra classes for the root section. Other section props (id, aria-*, data-*) land on it too. |

## Parts

### SetupChecklistItem (type)

{ id, title, description?, icon?, done?, action?, secondaryAction?, optional?, disabled? }: one task.

### SetupChecklistAction (type)

{ label, onClick?, href? }: a task's button; with href it renders as a link.

### SetupChecklistVariant (type)

"card" | "inline" | "floating".

### SetupChecklistSize (type)

"sm" | "md".

### SetupChecklistSlot (type)

The keys of classNames.

### SetupChecklistTone (type)

The tone union from lib/tones.

### SetupChecklistProps (type)

The props of SetupChecklist.

## Examples

- **Floating launcher**: A pill in the corner with the count; the list opens in a popover, or a bottom sheet on a phone.
- **All done**: Check the last step: the done state replaces the list, then the card folds up after doneDelay.
- **Inline in a sidebar**: variant="inline" and size="sm" under the navigation; optional steps stay out of the count.
- **Brand tone, done on action**: tone="brand" with markOnAction, so each Connect checks its step off.
- **Driven by your data**: Each item's done comes from the server; without onCompletedChange the checks only show state.

## See also

- [Onboarding Flow](https://wingo-ui.com/components/onboarding-flow) ([Markdown](https://wingo-ui.com/components/onboarding-flow.md))
- [Tour](https://wingo-ui.com/components/tour) ([Markdown](https://wingo-ui.com/components/tour.md))
- [Progress](https://wingo-ui.com/components/progress) ([Markdown](https://wingo-ui.com/components/progress.md))
- [Steps](https://wingo-ui.com/components/steps) ([Markdown](https://wingo-ui.com/components/steps.md))
- [Empty State](https://wingo-ui.com/components/empty-state) ([Markdown](https://wingo-ui.com/components/empty-state.md))
- [Admin Dashboard Page](https://wingo-ui.com/components/admin-dashboard-page) ([Markdown](https://wingo-ui.com/components/admin-dashboard-page.md))

---

Canonical: https://wingo-ui.com/components/setup-checklist
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt