Preferences Wizard

When to useCopy Anchor Link

• The user wants to set up or personalize lasting preferences the agent will use from now on: news topics, diet, travel style, notifications.
• Onboarding, where a few visual choices replace a long back-and-forth.

When not to useCopy Anchor Link

• The agent needs answers for this one task only. Use a Question Stepper.
• The user is booking, buying or submitting something. Use a Guided Flow.
• The user wants to tune the constraints of an answer the agent already gave. Use Preference Controls.

How the agent should use itCopy Anchor Link

• Keep it to 2–8 short steps, broad to specific, each with a 1–3 word title.
• Prefill value with the user's current settings when you know them; otherwise use sensible defaults. A skipped step keeps them.
• Mark a step required only when you can't work without it. Everything else can be skipped.
• Pick the input for the question: cards with icons for a handful of broad choices, chips for long or open lists, scale for a degree, rank for priorities, toggles for on/off settings, schedule for days and times.
• Only save on save. Store answers as the user's settings, keep your defaults for the skipped steps, and say in one line what changes.
• On dismiss, save nothing and don't ask again unless the user brings it up.
• Lifecycle: no expiresAt or fetchedAt; preferences don't go stale. If the agent starts a new wizard for the same settings before this one is finished, mark the old call superseded (supersededBy).

InputsCopy Anchor Link

Every step has id, title, an optional description and required, and one input:

InteractionCopy Anchor Link

• Progress you can see. The header shows the icon, "Step 1 of 4" and the step title (with a quiet Required tag when it is), with a segmented bar, one segment per step, under it. Skipped steps are hollow, and the bar's screen reader text names each step as done, skipped, current or not started. For cards and chips with a limit, the footer tracks it on the left ("2 selected · Pick at least 3"), beside a quiet Not now; Back appears from step 2. Option cards show their check only once picked; photo cards are 4:3 with the label on the photo.
• Focus follows the step. After moving, focus lands on the step heading, announced as "Step 2 of 5: Cuisines". Steps slide in their direction; with reduced motion they fade.
• Streaming. The header arrives first, then the steps one by one. The user can start straight away; Next on the newest step waits until its options are complete, and the review waits for the whole payload.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { preferencesWizardTool } from "@/components/genui/preferences-wizard.schema"

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

import { PreferencesWizard } from "@/components/genui/preferences-wizard"

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

  return (
    <PreferencesWizard
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      progress={loadProgress(part.toolCallId)}
      onProgress={(p) => saveProgress(part.toolCallId, p)}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "setup_preferences",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The agent receives one of:

{
  action: "save",
  answers: {
    topics: ["world", "tech", "climate"],
    sources: ["Harbor Post", "My Local Paper"],
    depth: 4,
    alerts: { breaking: true, followed: false, weekly: true },
  },
  skipped: ["digest"],
}
{ action: "dismiss" }

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

There are two ways to restore it, like the Checklist:

<PreferencesWizard
  {...part.input}
  progress={savedProgress}
  onProgress={(p) => saveProgress(part.toolCallId, p)}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Step: { id, title, description?, required?, input }. description is one short line under the title; don't repeat the pick limit, which the card already shows.

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

SourceCopy Anchor Link