Checklist

When to useCopy Anchor Link

• The user will carry out several steps over time: a cooking timeline, onboarding, a renewal, a launch.
• The user has things to gather and tick off: a packing list, documents to bring.
• Ticking things off helps them keep their place.

When not to useCopy Anchor Link

• The steps are things the agent will do itself. Show an action plan or the activity instead.
• There are only one or two steps. Say them in text.
• The list is information, not tasks. Use plain bullets.

How the agent should use itCopy Anchor Link

• Write each step as an action the user takes, in the order they'll do it.
• For a timeline, give each step a time ("12:30 PM", "Saturday") and, if it helps, a one-line description.
• For a list of things, use short labels only, and split long lists with group ("Clothing", "Toiletries").
• Set countLabel when a word makes the count clearer: "packed" shows "3/14 packed".
• Use meta only for an owner ("IT"), in a few words.
• Only add submitLabel when the user's progress changes what you do next, e.g. "I have everything" before confirming an appointment.
• Lifecycle: nothing to set. A checklist doesn't expire or go stale.

LayoutsCopy Anchor Link

The layout follows the data, so the agent never picks one:

Either layout can be split into sections with group. Sections appear in the order their first item does. The header shows the count ("1 of 8", or "3/14 packed" with countLabel) and a thin progress bar. Done items are struck through and muted.

Two kinds of historyCopy Anchor Link

A checklist is often used over hours, so there are two ways to restore it:

<Checklist
  {...part.input}
  progress={savedTicks}
  onProgress={(ids) => saveTicks(part.toolCallId, ids)}
  result={part.state === "output-available" ? part.output : undefined}
/>

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { checklistTool } from "@/components/genui/checklist.schema"

const tools = {
  [checklistTool.name]: tool({
    description: checklistTool.description,
    inputSchema: checklistTool.inputSchema,
  }),
}

Without submitLabel the checklist is the whole answer, so give the tool an execute that returns immediately. With it, the agent receives:

{ action: "submit", checked: ["form", "passport", "photo", "fee"] }

With LangGraphCopy Anchor Link

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

SchemaCopy Anchor Link

Item

Host props: status (streaming, ready, submitted), onResult, onProgress, progress, result and className.

SourceCopy Anchor Link