# Question (/docs/agent-ui/components/question)

Use a question when the agent needs facts only a person has before it goes on, like where to deploy or which checks to run. Every question is a fieldset in one form with one **Submit**, and once the host records the answers, they take the form's place.

<Example caption="Choose where to deploy, pick any checks and add a note, then press Submit. The form gives way to your answers.">
<Basic />

```tsx
"use client";
import type { Answers, Question as QuestionData } from "@kind-ui/agent-ui";
import { useState } from "react";
import { Question } from "@/components/ui/question";

const questions: QuestionData[] = [
  {
    id: "env",
    prompt: "Where should it deploy?",
    kind: "single",
    required: true,
    options: [
      { value: "staging", label: "Staging", description: "Safe to break." },
      { value: "prod", label: "Production", description: "Every user sees it." },
    ],
  },
  {
    id: "checks",
    prompt: "Which checks should run first?",
    kind: "multiple",
    options: [
      { value: "unit", label: "Unit tests" },
      { value: "e2e", label: "End-to-end tests" },
    ],
  },
  { id: "notes", prompt: "Anything the reviewers should know?", kind: "text", placeholder: "Optional notes" },
];

export default function QuestionExample() {
  const [submitted, setSubmitted] = useState<Answers>();
  return (
    <Question
      label="Deploy questions"
      questions={questions}
      submitted={submitted}
      onSubmit={(answers) => setSubmitted(answers)}
      onSkip={() => setSubmitted({})}
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/question
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/question-web
```

## Composition [#composition]

```text
Question
├── QuestionItem
│   ├── QuestionPrompt
│   ├── QuestionChoices
│   └── QuestionText
├── QuestionActions
│   ├── QuestionSubmit
│   ├── QuestionSkip
│   ├── QuestionStatus
│   │   └── QuestionStatusIcon
│   └── QuestionError
└── QuestionSummary
    └── QuestionSummaryIcon
```

`Question` renders these parts when you pass no children: a form named by its `label`, with a `QuestionItem` for each of the `questions`. Each item is a group named by its `QuestionPrompt`, holding UI SDK's radio group for a single choice, its checkbox group for a multiple choice, or a text box. `QuestionSubmit` and `QuestionSkip` are native buttons, and `QuestionStatus` or `QuestionError` sits beside them. `QuestionSummary` replaces the form once the answers are recorded.

## Usage [#usage]

### Questions [#questions]

Pass `questions`, each with an `id`, a `prompt` and a `kind` of `single`, `multiple` or `text`. Choice questions take `options` with a `value`, a `label` and an optional `description`; a text question takes a `placeholder`. Mark a question `required` and its prompt reads "Required".

```tsx
<Question
  label="Deploy questions"
  questions={[
    {
      id: "env",
      prompt: "Where should it deploy?",
      kind: "single",
      required: true,
      options: [
        { value: "staging", label: "Staging" },
        { value: "prod", label: "Production" },
      ],
    },
    { id: "notes", prompt: "Anything else?", kind: "text" },
  ]}
  onSubmit={(answers) => send(answers)}
/>
```

Answers are keyed by question id: an option's value for a single choice, a list of values for a multiple one, and the text for a text question. Pass `value` and `onValueChange` to own them, or `defaultValue` to start with some.

### Keyboard [#keyboard]

Each choice group is one Tab stop: the arrow keys move between radios and check them, and Space checks a checkbox. Enter on a choice submits the form, as it does in any form. In a text box, Enter adds a line and never submits.

### Submitting [#submitting]

Pass `onSubmit` to show **Submit**. It's disabled until every required question has an answer: a choice, or text that isn't blank. A press locks the form at once, so a second press, even on **Skip**, calls nothing, and "Sending answers" shows beside the buttons. Return a promise to hold the lock until it settles. A rejection unlocks the form, keeps every answer, and shows "Answers not sent. Try again."; screen readers hear "Answers not sent".

Pass `onSkip` to show **Skip**, which calls it with the answers so far.

### Recorded Answers [#recorded-answers]

Once the host has the answers, pass them back as `submitted`. The summary takes the form's place: "Answered" with each question and its answer, or "Skipped" when `submitted` holds none. Until `submitted` is set, a form whose call resolved stays locked. Screen readers hear "Answered" or "Skipped", and if **Submit** had focus, focus moves to the summary.

A new set of questions unlocks the form, and a late result for the old ones changes nothing.

### Motion [#motion]

Questions added after the form appears fade up, the summary fades in, and the radio and checkbox marks scale in. Under `prefers-reduced-motion`, or with `motion="reduced"`, these only fade, over 120 ms, and with `motion="none"` they change at once.

## API Reference [#api-reference]

### QuestionOptions

| Prop             | Type                                                                                         | Description                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `questions?`     | `Question[] \| undefined`                                                                    | The questions, in order, each its own fieldset in one form. Defaults to none.                                                                             |
| `value?`         | `Answers \| undefined`                                                                       | The answers by question id. Passing it controls them: change them in `onValueChange`. Don't pass it with `defaultValue`.                                  |
| `defaultValue?`  | `Answers \| undefined`                                                                       | The answers at first, when `value` isn't passed.                                                                                                          |
| `onValueChange?` | `((value: Answers, details: ChangeDetails<QuestionValueChangeReason>) => void) \| undefined` | Called when an answer changes, with what caused it. Cancel `details` to refuse the change.                                                                |
| `onSubmit?`      | `QuestionCallback \| undefined`                                                              | Called with the answers when they're sent. Shows Submit while set, available once every required question has an answer.                                  |
| `onSkip?`        | `QuestionCallback \| undefined`                                                              | Called with the answers so far when the questions are skipped. Shows Skip while set.                                                                      |
| `submitted?`     | `Answers \| undefined`                                                                       | The answers the host recorded, shown read-only in the form's place. Until it's set, a sent or skipped form stays locked; pass `{}` for skipped questions. |
| `label?`         | `string \| undefined`                                                                        | Names the form, like "Deploy questions". Default: `"Questions"`                                                                                           |
| `submitLabel?`   | `string \| undefined`                                                                        | Default: `"Submit"`                                                                                                                                       |
| `skipLabel?`     | `string \| undefined`                                                                        | Default: `"Skip"`                                                                                                                                         |
| `agentConfirm?`  | `boolean \| undefined`                                                                       | Whether an agent's `submit` and `skip` wait for a person to confirm (spec §6). Default: `true`                                                            |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                              | How new questions and the summary fade in. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                   |

### Agent [#agent]

An agent connected with `createAgent` finds the question by its label and reads its answers. It can `select` an option or `setText` for a question it names by id or prompt, and an unknown question is refused. It can `submit` once every required question has an answer, and `skip` while **Skip** shows. While `agentConfirm` is on, every action waits for a person to confirm, unless the host's `allow` lets it through.

### QuestionAgentActions

| Prop      | Type                                             | Description                                                                                                                                                                               |
| --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `select`  | `(questionId: string, value: string) => boolean` | Chooses `value` for a single or multiple choice question, toggling it in a multiple one. Returns `false` for an unknown question or option, a text question, or while the form is locked. |
| `setText` | `(questionId: string, text: string) => boolean`  | Writes a text question's answer. Returns `false` for an unknown or choice question, or while the form is locked.                                                                          |
| `submit`  | `(() => void) \| undefined`                      | Calls `onSubmit`. Offered only while it's set, every required question has an answer and nothing is pending.                                                                              |
| `skip`    | `(() => void) \| undefined`                      | Calls `onSkip`. Offered only while it's set and nothing is pending.                                                                                                                       |

<Caption>
Runs in React and Web Components. On `<kind-question>`, `questions`, `value`, `defaultValue` and `submitted` are properties, and other props are kebab-case attributes, so `submitLabel` is `submit-label`. Submit and Skip need the `can-submit` and `can-skip` attributes and fire `questionsubmit` and `skip` with the answers as `detail.value`: call `event.detail.waitUntil(promise)` to keep the form locked. The element fills in its form when it has no children.
</Caption>