Setup Checklist

Animated onboarding checklist with task rows, completion badges, and a live progress pill.

Installation

npx shadcn@latest add @iconiq/setup-checklist

File Structure

Usage

"use client";

import { FileText, Globe, Palette, Rocket } from "lucide-react";
import {
  SetupChecklist,
  SetupChecklistCard,
  SetupChecklistDescription,
  SetupChecklistHeader,
  SetupChecklistItem,
  SetupChecklistList,
  SetupChecklistProgress,
  SetupChecklistTitle,
} from "@/components/ui/setup-checklist";

export function SetupChecklistPreview() {
  return (
    <SetupChecklist
      defaultCompletedIds={["brand"]}
      onCompletedChange={(completedIds) => console.log(completedIds)}
    >
      <SetupChecklistCard>
        <SetupChecklistHeader>
          <SetupChecklistTitle>Onboarding Checklist</SetupChecklistTitle>
          <SetupChecklistDescription>
            Finish the remaining tasks to fully activate your workspace.
          </SetupChecklistDescription>
        </SetupChecklistHeader>
        <SetupChecklistList>
          <SetupChecklistItem
            description="Upload your logo and color palette so every page stays on-brand."
            icon={<Palette />}
            id="brand"
            title="Add Your Brand Assets"
          />
          <SetupChecklistItem
            description="Draft a landing page or post to start building your online presence."
            icon={<FileText />}
            id="content"
            title="Create Your First Page"
          />
          <SetupChecklistItem
            description="Link your domain name so visitors can find you at your own URL."
            icon={<Globe />}
            id="domain"
            title="Connect a Custom Domain"
          />
          <SetupChecklistItem
            description="Review your setup and make your workspace publicly available."
            icon={<Rocket />}
            id="launch"
            title="Publish and Go Live"
          />
        </SetupChecklistList>
      </SetupChecklistCard>
      <SetupChecklistProgress>Onboarding Progress</SetupChecklistProgress>
    </SetupChecklist>
  );
}

Props

Props
Description

SetupChecklist

children

Composition surface. Place SetupChecklistCard with the header and list inside, and SetupChecklistProgress after the card.

Type ReactNode

completedIds

Controlled list of completed item ids when the parent owns checklist state.

Type string[]

defaultCompletedIds

Initial completed item ids for uncontrolled usage.

Type string[]

onCompletedChange

Called with the next completed id list whenever a row is toggled.

Type (completedIds: string[]) => void

onItemToggle

Called with the toggled item id and its new completion state.

Type (id: string, completed: boolean) => void

className

Extra classes for the outer wrapper.

Type string

SetupChecklistItem

id

Stable id used in completedIds, defaultCompletedIds, and the toggle callbacks.

Type string

title

Row heading.

Type ReactNode

description

Muted supporting copy under the title.

Type ReactNode

icon

Leading icon rendered in a bordered tile.

Type ReactNode

onClick

Called on row click alongside the completion toggle, e.g. to navigate to the task.

Type (id: string) => void

className

Extra classes for the row button.

Type string

SetupChecklistProgress

children

Label rendered before the percentage, e.g. Onboarding Progress. Omit to show the percentage alone.

Type ReactNode

className

Extra classes for the pill wrapper row.

Type string

SetupChecklistCard, Header, Title, Description, List, Action

Structural parts that compose the card shell. Card animates in with a spring, Header wraps the Title heading and muted Description copy, List staggers its items on mount, and Action is a footer slot for your own CTA such as a submit button. Each accepts `children` and an optional `className`.

SetupChecklistCard renders the bordered card surface with the entrance spring.

SetupChecklistList renders a ul and staggers each SetupChecklistItem in with a soft rise.

SetupChecklistAction places your own button under the list — pair it with completedIds or onCompletedChange in the parent to enable submit when everything is done.

Because the copy is composed as children, the title, description, and progress label are fully yours — nothing is hardcoded in the component.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: motion, lucide-react.

Credits: Design inspired by Aditya.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Onboarding Checklist

Finish the remaining tasks to fully activate your workspace.

Onboarding Progress: 0%