affectUI › Components › Agents

Agent Plan

An agent's step-by-step plan to review before it runs – rename, drag to reorder, remove or add steps, then watch each one run with live timers and retry from a failed step.

Part of affectUI Pro. Install: npx shadcn@latest add https://www.affectui.com/r/agent-plan.json · Import from @/components/ui/agent-plan

When to use

  • An agent is about to do several things in a row and people should agree to the plan first
  • Long or expensive runs (tool calls, emails, writes) where a wrong order or an extra step costs real time
  • Showing the same plan as it executes – which step is running, how long each took, where it failed

When not to use

  • A single action that needs a yes or no – use Approval Card
  • Model reasoning without editable steps – use Thinking State
  • A user's own onboarding checklist – use Progress Tracker

Usage

import { useState } from "react";
import { AgentPlan, type PlanStep } from "@/components/ui/agent-plan";

export function PlanReview({ plan }: { plan: PlanStep[] }) {
  const [steps, setSteps] = useState(plan);
  const [status, setStatus] = useState<"draft" | "running" | "done">("draft");

  return (
    <AgentPlan
      title="Prepare the Q3 board update"
      estimate="~2 min"
      steps={steps}
      status={status}
      onChange={setSteps}
      onRun={(final) => {
        setStatus("running");
        agent.run(final); // stream step updates back into setSteps
      }}
      onCancel={() => agent.discard()}
      onRetry={(id) => agent.retryFrom(id)}
    />
  );
}

Props

NameTypeDefaultDescription
stepsPlanStep[]Controlled steps: { id, title, detail?, tool?, status?, duration?, error? }. Pair with onChange
defaultStepsPlanStep[][]Initial steps when uncontrolled – edits are kept inside the component
status"draft" | "running" | "done""draft"Review and edit, executing, or finished. Editing is only possible in draft
onChange(steps: PlanStep[]) => voidEvery edit during review: rename, remove, reorder, add
onRun(steps: PlanStep[]) => void"Run plan" pressed – gets the steps in their final order. Set status to "running" here. Also shows "Run again" on the tray once done
onCancel() => voidShows a Cancel button next to Run plan
onRetry(stepId: string) => voidShows "Retry from here" under failed steps
titlestringThe goal of the plan, shown as the heading and used as the list's label
estimatestringEstimated run time shown in review, e.g. "~2 min"
classNamestringExtra class on the root

Keyboard

  • Tab: Moves between steps, their remove buttons, the Add step field and the actions
  • ↑ / ↓: Moves focus to the previous or next step
  • Alt / ↑ / ↓: Moves the focused step up or down
  • Enter: Renames the focused step; Enter again saves. In Add step: adds the step at the end and keeps the field ready for the next one
  • Esc: Cancels a rename
  • Delete: Removes the focused step

Accessibility

  • The steps are an ordered list labelled with the plan's title; each step is focusable in review and describes its shortcuts
  • Moves, renames, removals and additions are announced in a polite live region ("Moved 'Draft the board memo' to position 3 of 5")
  • While running, each step carries its status as text, the active one has aria-current="step", and finished or failed steps are announced
  • The drag grip is pointer-only; Alt+arrow keys do the same from the keyboard
  • Icon buttons are labelled, focus rings show on keyboard focus only, and the folded-away Add step is inert while running

Responsive

  • Fills its container up to 460px; titles and details wrap, tool chips stay on one line
  • Below 400px the footer hint drops away, below 340px gutters tighten – works down to 320px
  • On touch screens the grip and remove button are always visible
  • Dark mode built in: switches when an ancestor (usually <html>) has the class dark or data-theme="dark"

Requirements

  • React 19

Related

  • Progress Tracker – Onboarding checklist with an animated progress bar, ticks that draw themselves and auto play
  • Tool Call Card – An agent's tool call in one line – live timer, status and summary, folds open to highlighted arguments and result with copy, retry on errors and a group that sums them up
  • Approval Card – An agent asks before it acts – risk badge, preview, Approve and Deny with shortcuts, a pausing countdown, and a smooth morph into a resolved row
  • Thinking State – AI working panel with a live timer, searched sources and thinking steps that appear one by one

Guides