AgentQuestionCard
StableThe assistant asks you a question in the middle of a task, with quick answers.
Also known as clarifying question, agent question, ask user, human input request
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Choose an approach
Should I plan the trip around museums or the beach?
<AgentQuestionCard
question="Should I plan the trip around museums or the beach?"
reason="approach"
runName="Trip plan"
options={[
{ id: "m", label: "Museums", description: "Indoor, good for rainy days" },
{ id: "b", label: "Beach", description: "Outdoor, relaxed pace" },
{ id: "x", label: "A mix of both" },
]}
onAnswer={(a) => console.log(a)}
/>Tap a choice. The card collapses to a summary and Change reopens it.
When to use it
The assistant stops to ask instead of guessing. A label says why it is asking, and quick choices, a typed answer, Let the agent decide and Skip mean the person is never stuck.
Made of: Reason label · Run name · Question · Two to four choices · Own-answer box and Send · Let the agent decide · Skip · Summary after answering
Use it for
- Asking the person to choose between two to four approaches.
- Asking for a fact the assistant cannot find itself.
- Asking someone to sign in, or to confirm a risky step, before the assistant goes on.
Not for
- Allowing or denying one specific action: use PermissionPrompt.
- Agreeing to a whole plan before work starts: use PlanCard.
- Suggested next prompts after a reply: use SuggestionChips.
Do and avoid
Which hotel should I book?
What time zone is Lisbon in?
Do
- Ask only when a wrong guess would cost the person time or money.
- Write the question so it can be answered without reading the log.
- Give two to four choices that really differ, and say how in one line.
- Always offer Let the agent decide and Skip.
Avoid
- Do not ask for passwords or codes in the text box.
- Do not use amber on a card that is already answered.
- Do not ask about things the assistant can find out itself.
- Do not stack many question cards at once. Use the inbox instead.
On a phone
- The answer options stack in one column on a phone and move to two columns from 640px wide.
- The text field is 44px tall with 16px text on a touch screen, and the Send button wraps below it when the row is narrow.
- Let the agent decide and Skip are buttons that wrap, so they stay reachable without scrolling sideways.
Seen in products
- Anthropic: on the hardest tasks the agent asks for clarification more than twice as often as on simple ones, and more often than people interrupt it.
- Anthropic gives the reasons for asking: proposing approaches 35%, gathering diagnostics 21%, requesting credentials 12%.
- Claude Code agent view: a peek panel shows the exact question, the wait time and a reply box with numbered choices.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| questionrequired | string | none | The question, in plain words. |
| reasonrequired | "approach" | "information" | "sign-in" | "risky-step" | none | Why the assistant is asking. Sets the label. |
| options | QuestionOption[] | [] | Quick answers ({ id, label, description? }). Only the first four are shown. |
| allowText | boolean | reason !== "sign-in" | Show the free-text answer. |
| answer | QuestionAnswer | null | none | Controlled answer ({ kind, value, label }). Omit to let the card keep its own. |
| onAnswer | (answer: QuestionAnswer) => void | none | Fires for an option, typed text, Let the agent decide, or Skip. |
| onReopen | () => void | none | Fires when the person chooses Change on the summary. |
| runName | string | none | Name of the run that asked. |
| labels | AgentQuestionCardLabels | none | Overrides visible text, including a reasons map. |
| className | string | none | Extra classes on the root. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one AgentQuestionCard switches all of this from its properties panel, across 8 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Reason | reason | Approach, Information, Sign-in, Risky-step |
| Allow text | allowText | On or off |
| RunName | runName | Any text |
| Question | question | Any text |
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- answered
- Once answered (or when answer is passed), the card collapses to a summary line with a Change button.
- sign-in
- Set reason to sign-in to show a lock tag and a hint not to type secrets, and hide the free-text box.
- agent decides
- Let the agent decide and Skip close the question with a matching summary.
- text answer
- Send is disabled until something is typed in the answer box.
- hover
- An option button gets a stronger border under the pointer.
- focus
- Options and buttons show a focus ring, and focus moves to the card after an answer or Change.
Tokens
Change one of these and every part that uses it follows.
--attention--attention-soft--attention-fg--line--radius-field--radius-card
Built in
- The card is a region named by its question.
- Choices are real buttons in a list, so Tab moves through them and Enter or Space picks one.
- The reason is written in words, so it does not depend on color.
- The own-answer box has a visible label.
- After an answer, keyboard focus moves to the summary, and after Change it moves back to the question.
- An answer given elsewhere is announced to screen readers.
- Sign-in questions have no text box by default, and a hint says never to type a password there.
What you need to do
- Write the question so it makes sense alone, because screen readers use it as the card's name.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide