Change Preview

When to useCopy Anchor Link

• Before any write to an external system: records, settings, budgets, permissions or content.
• When the user should see exact before/after values and be able to edit them before applying.
• When several related changes are proposed together and the user may want only some of them.

When not to useCopy Anchor Link

• The user asked a question. Answer it.
• There is no meaningful "before", e.g. sending a new message. Use a draft component instead.
• You can't read the current values. Fetch them first; never guess before.

InstallationCopy Anchor Link

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

This adds components/genui/change-preview.tsx and change-preview.schema.ts, and installs the shadcn primitives it uses.

UsageCopy Anchor Link

Register the tool with your agent. The exported definition carries the schema and the usage guidance:

import { streamText, tool } from "ai"
import { changePreviewTool } from "@/components/genui/change-preview.schema"

const result = streamText({
  model,
  messages,
  tools: {
    // No execute(): the call is completed by the user's decision in the UI.
    [changePreviewTool.name]: tool({
      description: changePreviewTool.description,
      inputSchema: changePreviewTool.inputSchema,
    }),
  },
})

Render the tool call, and return the user's decision as the tool result:

import { ChangePreview } from "@/components/genui/change-preview"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-propose_changes") return null

  return (
    <ChangePreview
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "propose_changes",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The agent receives one of:

{ action: "confirm", changes: [{ id, value, edited }], skipped: [id] }
{ action: "reject" }
{ action: "revise", note: "Cut the budget by 20%, not 40%" }

Request changes (the message icon in the footer) lets the user steer the proposal instead of accepting or rejecting it outright. On revise, apply nothing: address the note and show a new Change Preview.

Apply only the returned values. If the user edited a value, edited is true and value holds their version.

For other models, convert the schema with z.toJSONSchema(changePreviewSchema).

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

When a conversation is reloaded, pass the stored result back as result. The component renders its finished state (edits, skipped rows and the outcome) and never calls onResult again, so a decision can't be made twice. With the AI SDK, that's the tool call's output:

<ChangePreview
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

ChangeItem

Host props: status (streaming, ready, submitting, applied, rejected, revised), onResult, result and className.

SourceCopy Anchor Link