---
title: "Todo List | Free React & Tailwind Agents Component | Motion UI"
canonical: "https://blacknest.dev/motion/c/agents/todo-list"
github_source: "https://github.com/Rkj0123/motion-ui-skill/blob/main/components/agents/todo-list.tsx"
install_command: "npx motion-ui-skill add todo-list"
dependencies: ["clsx","lucide-react","motion","react","tailwind-merge"]
category: "agents"
subcategory: "agents"
---

# Todo List

> A collapsible agent task plan with morphing status marks, a completion count, compact metadata, and smooth list updates.

## Install

```bash
npx motion-ui-skill add todo-list
```

## Dependencies

- `clsx`
- `lucide-react`
- `motion`
- `react`
- `tailwind-merge`

## Usage

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import { useEffect, useRef, useState } from "react";
import {
  type TodoItem,
  TodoList,
} from "@/components/agents/todo-list";

const TASKS = [
  "Inspect the current data flow",
  "Update the response schema",
  "Add coverage for edge cases",
  "Run checks and prepare the result",
];

const TICKS_PER_TASK = 4;

function itemsAtStep(step: number): TodoItem[] {
  return TASKS.map((title, index) => ({
    id: `task-${index}`,
    title,
    status:
      step >= (index + 1) * TICKS_PER_TASK
        ? "completed"
        : step >= index * TICKS_PER_TASK
          ? "in-progress"
          : "pending",
    progress:
      step >= index * TICKS_PER_TASK &&
      step < (index + 1) * TICKS_PER_TASK
        ? ((step % TICKS_PER_TASK) + 1) * 25
        : undefined,
    detail:
      step >= index * TICKS_PER_TASK &&
      step < (index + 1) * TICKS_PER_TASK
        ? `${((step % TICKS_PER_TASK) + 1) * 25}%`
        : undefined,
  }));
}

function TodoRun() {
  const [step, setStep] = useState(0);
  const timer = useRef<number | undefined>(undefined);

  useEffect(() => {
    if (step >= TASKS.length * TICKS_PER_TASK) return;
    timer.current = window.setTimeout(() => setStep((value) => value + 1), 280);
    return () => {
      if (timer.current) window.clearTimeout(timer.current);
    };
  }, [step]);

  return <TodoList items={itemsAtStep(step)} title="Implementation plan" />;
}

export function TodoListPreview() {
  const [run, setRun] = useState(0);

  return (
    <div className="relative h-[330px] w-full max-w-lg">
      <TodoRun key={run} />
      <button
        type="button"
        onClick={() => setRun((value) => value + 1)}
        className="absolute bottom-0 left-0 inline-flex items-center gap-1.5 rounded-full px-2 py-1 text-xs font-medium text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
      >
        <RotateCcw className="size-3" />
        Replay
      </button>
    </div>
  );
}
```

## API Reference

### TodoList

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `TodoItem[]` | — | Yes | — |
| `title` | `ReactNode` | `To-dos` | No | — |
| `open` | `boolean` | — | No | — |
| `defaultOpen` | `boolean` | `true` | No | — |
| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
| `collapseOnComplete` | `boolean` | `true` | No | — |
| `maxHeight` | `number` | `248` | No | — |
| `className` | `string` | — | No | — |

## Source Files

- [components/agents/todo-list.tsx](https://github.com/Rkj0123/motion-ui-skill/blob/main/components/agents/todo-list.tsx)
- [components/agents/agent-disclosure.tsx](https://github.com/Rkj0123/motion-ui-skill/blob/main/components/agents/agent-disclosure.tsx)
- [components/motion/action-swap-roll.tsx](https://github.com/Rkj0123/motion-ui-skill/blob/main/components/motion/action-swap-roll.tsx)
- [components/motion/action-swap.tsx](https://github.com/Rkj0123/motion-ui-skill/blob/main/components/motion/action-swap.tsx)
- [lib/ease.ts](https://github.com/Rkj0123/motion-ui-skill/blob/main/lib/ease.ts)
- [lib/utils.ts](https://github.com/Rkj0123/motion-ui-skill/blob/main/lib/utils.ts)
