Preference Controls

When to useCopy Anchor Link

• The agent produced an answer that depends on a few constraints (a budget, a pace, a tone, a length, dates, must-haves), and the user is likely to want it redone with different ones.
• The user asks to make an answer cheaper, shorter, more casual or more relaxed, or to change what matters most.

When not to useCopy Anchor Link

• The user still has to give the inputs for a first answer. Ask with a Generated Form or a Question Stepper instead.
• The numbers can be recomputed on the spot without the agent. Use a Simulation or a Calculator, which recompute locally.
• The user is choosing between finished alternatives. Use Draft Options.

How the agent should use itCopy Anchor Link

• Show it next to the answer it controls, and name that answer in appliesTo ("your 5-day Lisbon itinerary"). It names the button ("Update itinerary") and is read to screen readers; it isn't shown as a subtitle.
• Only expose constraints you actually used, each set to the value behind the current answer.
• Use stable ids. On update, redo the answer with every value in values and say what changed; changed lists the ids that differ from what you sent.
• After an update, call the tool again with the new values as the current ones, so the user can keep iterating from there.
• On reset, go back to the answer made with the values you sent.
• Set live only when regenerating is cheap and fast. Otherwise the user presses Update.
• Lifecycle: no expiresAt or fetchedAt; the constraints don't go stale on their own. When the agent issues a new set of controls without the user having sent anything (they typed a new request instead), mark the old call superseded so only the latest one is usable.

ControlsCopy Anchor Link

controls is a list of 1–8 controls, discriminated by type. Each one shows its label and current value; they sit in one column, or two when the card is wide enough (a container query, so it adapts to the chat column, not the window).

Presets, changes and sendingCopy Anchor Link

Presets sit above the controls as a segmented row. Choosing one fills the values it lists and leaves the rest; when the values match no preset, the row shows Custom.

The footer's quiet line compares the current values with the ones the agent sent, once something differs: "Budget: €1,800 → €650 · Activities per day: 4 → 2". Priorities compare by order; chips compare as a set, so "added Vegetarian options; removed Free cancellation".

Update is off until something differs, and again once exactly those values have been sent. The component never locks: after a send the footer reads "Sent · updating" until the host passes new props (the agent's regenerated values) or moves status from submitting back to ready. Edits made in the meantime are kept. Reset discards edits; if an update was already sent, it also sends reset.

With live, there's no Update button. Each change is sent 600 ms after the user stops adjusting, and the footer shows "Updating…" while the agent works. Moving everything back to the starting values sends reset.

The diffing, change summary, preset matching, formatting and batching are pure functions in preference-controls-utils.ts.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { preferenceControlsTool } from "@/components/genui/preference-controls.schema"

const tools = {
  // No execute(): each update comes back from the UI.
  [preferenceControlsTool.name]: tool({
    description: preferenceControlsTool.description,
    inputSchema: preferenceControlsTool.inputSchema,
  }),
}

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

The agent receives one of:

{
  action: "update",
  values: { budget: 650, pace: 2, priorities: ["views", "food", "museums", "nightlife"], must: ["Free cancellation"] },
  changed: ["budget", "pace", "priorities"],
}
{ action: "reset" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "adjust_preferences", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer. To keep one card on screen across updates, push to the same UI message id with the new values; the component rebases on the new props.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The component shows the values that were sent (or the original values, for reset) read-only, with the change summary, and never calls onResult. The user keeps iterating in the latest call.

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

SchemaCopy Anchor Link

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

SourceCopy Anchor Link