Setup Checklist React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Pro item: the CLI needs a Pro account. See plans

Usage

Import SetupChecklist from @/components/ui/setup-checklist.

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

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

• defaultActivedefault ""
  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.

• titledefault "Get started"
  ReactNode

  The heading of the card and the launcher's text.

• descriptiondefault "Finish setting up your workspace."
  ReactNode

  One line under the title.

• progressLabeldefault "(done: number, total: number) => `${done} of ${total} done`"
  (done: number, total: number) => ReactNode

  The count next to the bar; a string result also names the bar for screen readers.

• variantdefault "card"
  "card" | "inline" | "floating"

  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.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Color of the checks, the bar, the main action and the launcher. Brand is opt-in.

• colordefault ""
  string

  Any CSS color; replaces the tone.

• sizedefault "md"
  "sm" | "md"

  md for a dashboard card; sm is denser, for a sidebar or a popover.

• collapsibledefault true
  boolean

  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.

• defaultOpendefault true
  boolean

  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.

• dismissibledefault true
  boolean

  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.

• dismissLabeldefault "Dismiss"
  string

  The x button's accessible name and the done state's button text.

• doneTitledefault "You're all set"
  ReactNode

  The heading of the done state that replaces the list.

• doneDescriptiondefault "Every setup step is done."
  ReactNode

  The line under the done heading.

• doneDelaydefault 4000
  number

  Milliseconds after everything is done before a collapsible card folds up; 0 keeps it open.

• markOnActiondefault false
  boolean

  A click on a task's main action also marks it done (for actions that finish the task, like Connect).

• optionalLabeldefault "Optional"
  string

  The tag on optional tasks.

• completedLabeldefault "Completed"
  string

  Read by screen readers after a finished task's title.

• toggleLabeldefault "Show or hide steps"
  string

  The tooltip of the header toggle.

• responsivedefault true
  boolean

  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

FAQ

More React feedback components