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, 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({
      items: z.array(
        z.object({
          id: z.string(),
          text: z.string(),
          status: z.enum(["pending", "active", "done", "failed"]),
          reason: z.string().optional(),
        }),
      ),
    }),
    execute: async ({ items }) => ({ count: items.length }),
    render: ({ args }) => <TodoList 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", 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" },
];

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>
    <span>Todos</span>
    <span>{/* n/m, or n/m · rev r when revision is set */}</span>
  </div>
  <ul>
    <li>
      <span>{/* status icon: check, spinner, cross, or empty box */}</span>
      <span>{/* the status as visually hidden text */}</span>
      <div>
        <span>{/* item text */}</span>
        <p>{/* optional failure reason */}</p>
      </div>
    </li>
    {/* one row per item */}
  </ul>
</div>

Each row shows one of four status icons: a checked box for done, a spinning loader for active, a red cross for failed, 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. Failed rows may include a reason below the item text. Text dims and gets struck through when done, reads at full opacity when active, sits at reduced opacity while pending, and uses error styling when failed. Rows key off item.id; passing a new array with the same ids only restyles the existing rows, while a genuinely 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. With zero items the header still renders 0/0 and the list is simply empty; there is no placeholder message. revision is decorative and does not affect the count or the render; it only appends · rev {revision} next to the ratio when you pass a number.

Examples

Item states

The four 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" },
  ]}
/>

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