Todo list

npx shadcn@latest add "@assistant-ui/elements-todo-list"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-todo-list"

A todo list shows the plan an agent is working through right now: what is done, what is active, what failed, what was cancelled, and what is still pending. With a runtime the list comes from a tool call the model keeps rewriting as it works; standalone you pass the items in yourself.

Getting started

import { defineToolkit } from "@assistant-ui/react";
import { z } from "zod";
import { TodoList } from "@/components/assistant-ui/elements/todo-list";

export const toolkit = defineToolkit({
  update_todos: {
    type: "frontend",
    description: "Replace the visible working list with the current plan.",
    parameters: z.object({
      title: z.string().optional(),
      description: z.string().optional(),
      maxVisible: z.number().optional(),
      items: z.array(
        z.object({
          id: z.string(),
          text: z.string(),
          description: z.string().optional(),
          status: z.enum(["pending", "active", "done", "failed", "cancelled"]),
          reason: z.string().optional(),
        }),
      ),
    }),
    execute: async ({ items }) => ({ count: items.length }),
    render: ({ args }) => (
      <TodoList
        title={args.title}
        description={args.description}
        maxVisible={args.maxVisible}
        items={args.items ?? []}
      />
    ),
  },
});

"use client";

import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { toolkit } from "./toolkit";

export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();
  const config = AuiConfig({ tools: Tools({ toolkit }) });
  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

"use client";

import { useState } from "react";
import { TodoList, type TodoItem } from "@/components/assistant-ui/elements/todo-list";

const initialItems: TodoItem[] = [
  { id: "1", text: "Read the failing test", description: "Trace the current behavior.", status: "done" },
  { id: "2", text: "Reproduce locally", status: "active" },
  { id: "3", text: "Write the fix", status: "pending" },
  { id: "4", text: "Re-run the suite", status: "failed", reason: "Tests timed out" },
  { id: "5", text: "Update the old fixture", status: "cancelled" },
];

export function Plan() {
  const [items, setItems] = useState(initialItems);
  return <TodoList items={items} />;
}

function advance(id: string) {
  setItems((prev) =>
    prev.map((item) =>
      item.id === id
        ? { ...item, status: item.status === "pending" ? "active" : "done" }
        : item,
    ),
  );
}

Anatomy

<div data-slot="todo-list">
  <div>
    <div>
      <span>Todos</span>
      <p>{/* optional list description */}</p>
    </div>
    <span>{/* n/m, or n/m · rev r when revision is set */}</span>
  </div>
  <ul>
    <li data-status="pending | active | done | failed | cancelled">
      <span>{/* status icon: check, spinner, cross, dash, or empty box */}</span>
      <span>{/* the status as visually hidden text */}</span>
      <div>
        <span>{/* item text */}</span>
        <p>{/* optional item description or failure reason */}</p>
      </div>
    </li>
    {/* one row per item */}
  </ul>
  <button aria-expanded="false">Show N more</button>
</div>

Each row shows one of five status icons: a checked box for done, a spinning loader for active, a red cross for failed, a muted dash for cancelled, and an empty outlined box for pending. The icon is decorative; every row carries its status as visually hidden text so a screen reader announces it alongside the item. Item descriptions appear below pending, active, and done items. A failed item's reason takes that place when present. Done and cancelled text is struck through in the muted foreground. Rows key off item.id; passing a new array with the same ids only restyles the existing rows, while a new id mounts a row that fades and slides in.

A failed item is terminal but it is not a success, so it counts toward the denominator and never toward the numerator: three items that have all settled with one of them failed read 2/3, not 3/3. A cancelled item has left the plan, so it counts toward neither: three items with two done and one cancelled read 2/2. With zero items the header still renders 0/0 and the list is empty, with no placeholder message. revision does not affect the count; it only appends · rev {revision} next to the ratio when you pass a number.

Examples

Item states

The five states rendered together, independent of how the list is produced:

<TodoList
  items={[
    { id: "1", text: "Read the failing test", status: "done" },
    { id: "2", text: "Reproduce locally", status: "active" },
    { id: "3", text: "Write the fix", status: "pending" },
    { id: "4", text: "Run deployment", status: "failed", reason: "Timed out" },
    { id: "5", text: "Replace the old fixture", status: "cancelled" },
  ]}
/>

Fold a long list

maxVisible keeps the first rows in view, then keeps any later active or failed row visible as well. The button reveals the remaining rows in their original order:

<TodoList
  maxVisible={3}
  items={[
    { id: "1", text: "Read the failing test", status: "done" },
    { id: "2", text: "Reproduce locally", status: "done" },
    { id: "3", text: "Write the fix", status: "pending" },
    { id: "4", text: "Run typecheck", status: "active" },
    { id: "5", text: "Run unit tests", status: "failed", reason: "Timed out" },
    { id: "6", text: "Update the changelog", status: "pending" },
    { id: "7", text: "Publish", status: "pending" },
  ]}
/>

Where the list comes from

import { useToolArgsStatus } from "@assistant-ui/react";

function TodoToolUI({ args }: { args: { items?: TodoItem[] } }) {
  const { propStatus } = useToolArgsStatus<{ items: TodoItem[] }>();
  return (
    <TodoList
      items={args.items ?? []}
      className={propStatus.items === "streaming" ? "opacity-70" : undefined}
    />
  );
}

function addItem(text: string) {
  setItems((prev) => [
    ...prev,
    { id: crypto.randomUUID(), text, status: "pending" },
  ]);
}

Restyle the list

Both lanes take className on the root, and the revision counter uses the shared mono surface from surfaces.tsx.

<TodoList className="max-w-md gap-2" items={items} revision={3} />

API reference