Generated Form

When to useCopy Anchor Link

• The agent needs several pieces of structured data to create or update a record: a new contact, a shipping address, an event RSVP.
• The values are the user's to provide, and the agent can't look them up.

When not to useCopy Anchor Link

• You need one or two decisions. Use the Question Stepper or ask in a sentence.
• The agent can find the values in data, files or earlier messages. Look them up, and prefill or skip those fields.
• The user is choosing among records the agent fetched. Use the Entity Picker.

How the agent should use itCopy Anchor Link

• Never ask for passwords, payment card numbers, bank details or government IDs. Send the user to the system's own secure page instead.
• Keep it to 10 fields or fewer, in the order the user thinks about them, with required fields first.
• Prefill default from real records (the saved address, the account owner) and mark only truly necessary fields required.
• select options are data-bound. They come from the system the agent will write to, never invented.
• Use pattern only for real format rules, always with a patternMessage.
• Reach for the specific type: money for an amount, phone for a number, tags for a free list, mention for people you fetched.
• Do nothing with the data until submit arrives. On cancel, stop.

Beyond text: money, phone, tags and mentionsCopy Anchor Link

Four field types cover what text fields get wrong:

money is an amount the user decides (a budget, a price cap), never card or account numbers. mention options are data-bound: the people or records you fetched, with value their id and label their name.

{
  action: "submit",
  values: { budget: 24000, topics: ["launch", "retention"], notes: "Review with @Priya Nair" },
  mentions: { notes: ["usr_priya"] },
}

ValidationCopy Anchor Link

Errors are linked to their control with aria-describedby, and invalid controls carry aria-invalid. Checks cover required, email format, number and money min/max, money precision, phone plausibility, tag count, text length, date bounds, select options and pattern. The rules are exported as validateFormField, so a server can re-run them.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { generatedFormTool } from "@/components/genui/generated-form.schema"

const tools = {
  // No execute(): the call is completed by the user's submission in the UI.
  [generatedFormTool.name]: tool({
    description: generatedFormTool.description,
    inputSchema: generatedFormTool.inputSchema,
  }),
}

import { GeneratedForm } from "@/components/genui/generated-form"

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

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

The agent receives one of:

{ action: "submit", values: { first_name: "Dana", guests: 1, save: true, notes: null } }
{ action: "cancel" }

Values are keyed by field id. number and money fields are numbers, checkboxes are booleans, tags are arrays, and empty optional fields are null. When a mention field names someone, the result also has mentions.

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The form renders the submitted values read-only (or the cancelled state) and never calls onResult again.

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

SchemaCopy Anchor Link

FormField

Host props: status (streaming, ready, submitting, submitted, cancelled), onResult, result and className.

SourceCopy Anchor Link