# Task List

> A React to-do list: a checklist that strikes out completed tasks and moves them to the bottom, with each row also exported as TaskItem.

- Type: React component (Tables & Lists)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add task-list`
- Docs: https://wingo-ui.com/components/task-list

## Interaction

Click or tap a row to toggle it. Ticking fills the circle and draws a check, a line strikes through the label, the row gives a little flick, then it springs down to join the finished tasks at the bottom. Unticking runs the same road backwards and brings the row back up. Rows are real checkboxes, so Tab and Space or Enter work too.

## Installation

```bash
npx wingo-ui@latest add task-list
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/task-list.json`

Files:

- `components/ui/task-list.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
"use client"

import { TaskList } from "@/components/ui/task-list"

export function Demo() {
  return (
    <TaskList
      defaultTasks={[
        { id: "ship", label: "Ship a new component to the registry", done: true },
        { id: "preview", label: "Record a preview for the gallery" },
        { id: "star", label: "Star the repository" },
      ]}
    />
  )
}

// one row on its own, no list around it (see TaskItem under Parts):
// <TaskItem label="Star the repository" size="sm" onCheckedChange={setDone} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Row size. Text, circle, padding and radius all scale together, and the circle always matches one line of the label. |
| `accent?` | `string` | `"#FF5F2E"` | Any CSS color for the filled circle and the focus ring. The strike and the faded text stay grey. |
| `surfaceColor?` | `string` | `"auto"` | Fill of each row card, any CSS color. Auto is white on light pages and #1F1F1F on dark ones. |
| `textColor?` | `string` | `"auto"` | Color of open task labels, any CSS color. Auto is a near black or near white that follows the theme. |
| `doneTextColor?` | `string` | `"auto"` | Color of finished task labels and of the strike line, any CSS color. Auto is a mid gray tuned per theme. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Corner radius of each row card: square, 4px tighter, the original 10 / 14 / 16px per size, 6px rounder, or a pill. |
| `checkColor?` | `string` | `"#ffffff"` | Any CSS color for the tick drawn inside the filled circle. |
| `strike?` | `boolean` | `true` | Draws a line through finished labels. Off, they only fade to doneTextColor. |
| `reorder?` | `boolean` | `true` | Springs finished tasks down to the bottom of the list, and back up when reopened. Off, every row stays where it is. |
| `completedLabel?` | `string` | `"completed"` | Announced after a task label when it is ticked, e.g. "finalizat". |
| `reopenedLabel?` | `string` | `"reopened"` | Announced after a task label when it is unticked. |
| `tasks?` | `Task[]` |  | The rows to show, each one an id, a label, and an optional done flag. Pass this with onTasksChange to drive the list yourself. |
| `defaultTasks?` | `Task[]` | `"[]"` | The rows to start with when you are not driving the list. The list tracks which ones are done on its own. |
| `onTasksChange?` | `(tasks: Task[]) => void` |  | Called with the full list every time a row is ticked or unticked. |
| `className?` | `string` |  | Extra classes merged onto the root element (data-slot="task-list"); other ul props are spread onto it too. |

## Parts

### TaskItem (component)

One row on its own, no list around it: a checkbox button that ticks, strikes and flicks. The list renders one per task. Takes button props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | The task text. |
| `checked?` | `boolean` |  | Controlled state; pair it with onCheckedChange. |
| `defaultChecked?` | `boolean` | `false` | Starting state when uncontrolled. |
| `onCheckedChange?` | `(checked: boolean) => void` |  | Called on every toggle. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Same scale as the list. |
| `radius?` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | `"md"` | Corner radius of the card. |
| `accent?` | `string` | `"#FF5F2E"` | Fill of the ticked circle and the focus ring. |
| `checkColor?` | `string` | `"#ffffff"` | Color of the tick. |
| `surfaceColor?` | `string` | `"auto"` | Card fill; auto is white light, #1F1F1F dark. |
| `textColor?` | `string` | `"auto"` | Label color while open. |
| `doneTextColor?` | `string` | `"auto"` | Label color once done. |
| `strike?` | `boolean` | `true` | Draws the line through a finished label. |
| `onSettled?` | `() => void` |  | Fires once the tick, strike and flick have finished. |
| `onReverted?` | `() => void` |  | Fires once the untick has finished. |

### Task (type)

One entry of tasks: { id, label, done? }.

## Examples

- **Onboarding checklist**: Controlled with tasks and onTasksChange, so the header can count what is done and fill a progress bar.
- **Keep the order**: reorder and strike off: ticked rows stay in place and the label dims without a line; green accent, pill-shaped rows.
- **A single TaskItem**: Each row is exported as TaskItem: label, checked or defaultChecked with onCheckedChange, size and accent. onSettled and onReverted fire when its animation has finished.

## See also

- [List](https://wingo-ui.com/components/list) ([Markdown](https://wingo-ui.com/components/list.md))
- [Checkbox](https://wingo-ui.com/components/checkbox) ([Markdown](https://wingo-ui.com/components/checkbox.md))
- [Kanban](https://wingo-ui.com/components/kanban) ([Markdown](https://wingo-ui.com/components/kanban.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))

---

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