Question Stepper

When to useCopy Anchor Link

• You need 1–5 decisions from the user before you can do the work well.
• The answer would materially change the result, and you can't infer it.
• The choices are discrete enough that you can propose good options.

When not to useCopy Anchor Link

• You can find the answer yourself in data, files or earlier messages. Look it up.
• It's a single yes/no question. Ask in one sentence, or use follow-up chips.
• You'd need more than 5 questions. Proceed with sensible defaults and ask afterwards.
• You're collecting record data, such as an address or a new contact. Use a generated form.

InteractionCopy Anchor Link

While the tool call is streaming, the user can already answer the questions that have arrived. Submitting waits until the payload is complete.

The card shows one question at a time: a segmented progress bar, the question, and its options. title and each question's description are read to screen readers but not shown, so put anything the user must see in the question or the options. header labels each answer in the submitted summary. A required question is marked with an asterisk.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/question-stepper.json

UsageCopy Anchor Link

import { tool } from "ai"
import { questionStepperTool } from "@/components/genui/question-stepper.schema"

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

import { QuestionStepper } from "@/components/genui/question-stepper"

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

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

The agent receives one of:

{
  action: "submit",
  answers: [
    { id: "source", status: "answered", selected: ["sheets"] },
    { id: "metrics", status: "answered", selected: ["score_trend"], text: "Churn by cohort" },
    { id: "audience", status: "delegated" },
    { id: "region", status: "skipped" },
  ],
}
{ action: "dismiss" }

text holds the Other input for option questions, and the answer for text questions.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "ask_questions", 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 (the answer summary) and never calls onResult again, so a decision can't be made twice. With the AI SDK, that's the tool call's output:

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

SchemaCopy Anchor Link

Question

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

SourceCopy Anchor Link