To-do List

When to useCopy Anchor Link

• The user asks about their own to-do list: "what's on my list today?", "what's overdue?".
• The user asks to add, reschedule or tick off tasks in their tasks app.
• The user wants a list they'll keep and edit, such as a packing or shopping list.

When not to useCopy Anchor Link

• The steps are the agent's instructions for one task, like a recipe or a setup guide. Use a Checklist.
• The items are things the agent will do itself. Show a plan instead.
• Work items move between stages on a team board. Use a Kanban Board.
• The agent can't read the user's list. Fetch it first; never invent their tasks.

How the agent should use itCopy Anchor Link

• Pass items exactly as the tasks app returns them, in order. Never change their text, dates or done state yourself.
• To add a task the user asked for, include it with isNew: true and a new id. It shows as "Added" and is saved only when the user saves.
• Put your own ideas in suggestions, each with a short reason. They show under "Suggested" with Add and a dismiss button; the reason is a tooltip and is read to screen readers. Never mix them into items.
• Pick groupBy for the question: due for "today" or "overdue", tag for categorized lists like packing, none or priority when the user's own order matters (only those two can be reordered by hand).
• Write nothing until the result arrives, then apply exactly the returned changes. On discard, write nothing.
• Lifecycle: the list is the user's own and they keep working in it, so don't set expiresAt. Set fetchedAt and staleAfterMs (e.g. an hour) when the list was read from a tasks app that other devices also edit, so the Renderer offers a refresh. When the agent shows the same list again with fresh data, supersede the old call.

EditingCopy Anchor Link

Every edit is collected locally and counted in the footer ("3 changes"). Nothing is written until the user presses Save to Tasks app (the label uses source.label, or just "Save"). Discard goes back to the last saved state. The header shows only the title: the counts are read to screen readers, and the Save button names the source.

Due groups are computed in timeZone (or the viewer's): Overdue, Today, Tomorrow, This week (2 to 6 days out), Later and No date. A date-time that has passed today counts as overdue. Pass now to fix the moment they're computed from; it defaults to the viewer's clock after mount. Setting a date from the options panel stores a plain date.

Done items are the one place the list starts collapsed, so the open tasks stay in view. Set hideDone to leave them out.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/todo-list.json

UsageCopy Anchor Link

import { tool } from "ai"
import { todoListTool } from "@/components/genui/todo-list.schema"

const tools = {
  // No execute(): the call is completed by the user's save or discard.
  [todoListTool.name]: tool({
    description: todoListTool.description,
    inputSchema: todoListTool.inputSchema,
  }),
}

<TodoList
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  progress={savedProgress}
  onProgress={(p) => saveProgress(part.toolCallId, p)}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) =>
    part.state === "output-available"
      ? saveTasks(result) // later saves: write directly
      : addToolResult({ tool: "show_todos", toolCallId: part.toolCallId, output: result })
  }
/>

The agent receives one of:

{
  action: "save",
  changes: {
    added: [{ id: "new-1", text: "Call the bank", done: false, due: "2026-10-09" }],
    updated: [{ id: "t-112", fields: { due: "2026-10-12", priority: null } }],
    completed: ["t-110"],
    reopened: [],
    deleted: ["t-113"],
    reordered: ["t-111"],
    order: ["t-111", "t-110", "t-112", "new-1"],
  },
}
{ action: "discard" }

changes is the smallest set that turns the list as loaded into the user's. A cleared field is null. reordered lists the fewest items whose move explains the new order (moving one item and back again isn't a change), and order gives every id in the final order whenever anything moved. Ids in added are the component's own (new-1, …); the tasks app assigns real ones.

A to-do list is ongoing, so the list stays usable after a save: it shows "Saved · 3 changes" and counts later edits against the saved state. Each later save calls onResult again with only the changes since the previous one. Send the first as the tool result and write later ones straight to the tasks app.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_todos", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

There are two ways to restore the list:

A result that arrives after mount (the user just saved) doesn't lock the list.

SchemaCopy Anchor Link

TodoItem

Host props: status (streaming, ready, saving, saved, discarded), onResult, onProgress, progress, result, now and className.

SourceCopy Anchor Link