Checklist

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add checklist

Usage#

Anatomy#

import {
  Checklist,
  ChecklistHeader,
  ChecklistTitle,
  ChecklistDescription,
  ChecklistProgress,
  ChecklistItems,
  ChecklistItem,
  ChecklistItemContent,
  ChecklistItemTitle,
  ChecklistItemDescription,
  ChecklistItemAction,
} from "@/components/ui/checklist"

<Checklist>
  <ChecklistHeader>
    <ChecklistTitle />
    <ChecklistDescription />
    <ChecklistProgress />
  </ChecklistHeader>
  <ChecklistItems>
    <ChecklistItem>
      <ChecklistItemContent>
        <ChecklistItemTitle />
        <ChecklistItemDescription />
      </ChecklistItemContent>
      <ChecklistItemAction />
    </ChecklistItem>
  </ChecklistItems>
</Checklist>

Item states#

Every ChecklistItem carries a status, drawn by the one task mark every task list in the kit shares: 16px, centred on the title's first line. A complete row fills it with ink and a tick and de-emphasizes the title; active marks the one recommended next step with an ink ring half filled, started but not done, and the primary action; the row stays flat, so the button is what draws the eye. todo rows wait quietly with an empty ring and an outline action.

Progress & completion#

Pass value (completed count) and total to the root; ChecklistProgress derives the bar, the “X of Y” label and the percentage itself. When every step is done the bar eases from ink to success-green and the label swaps to All steps complete.

Density#

Like Card and Dialog, the Checklist reads the density context (or a density prop). Density tunes the card and row padding only, and it is compact unless set. The indicator footprint is fixed at both densities, so the left rail lines up identically.

Tasks the reader ticks#

Give a ChecklistItem checked and onCheckedChange (or defaultChecked to let it keep its own state) and it becomes a task list: the indicator turns into the task mark, a real checkbox drawn like the small Checkbox only round, 16px and centred on the title's first line, with a tick in the colour of the surface beneath. It is named by the item's title, the whole row is its hit area, and a ticked title is struck through as it mutes. Leave value and total off the root and the Checklist counts its own items, so the bar follows every tick with no wiring. A row's ChecklistItemAction stays its own target above the hit area.

Inside a Card#

variant="plain" drops the Checklist's own contour and outer padding, so it sits inside a Card (or any surface that already frames it) without a frame inside a frame. The Card's header carries the heading; the indicators line up with it, and the row pills bleed into the Card's padding the way List's plain rows do. ChecklistProgress can lead the header on its own.

The task mark on its own#

ChecklistMark draws the same mark without the Checklist around it, for a task list something else lays out: the steps of an Accordion, a row that is already a button. An empty ring while the task waits, an ink ring half filled on the active step, the ink fill with a tick once it is complete: fill only ever means done. It centres itself on a text-sm first line, so put it in an items-start row. It is decoration, so the row says the state in words.

API reference#

FAQ#