# Questionnaire

Asks one question at a time in a soft tray, with single or multiple answers, shortcuts, validation, restore, and conditional steps.

Tier: Free

## Installation

```bash
npx shadcn add @fetaui/questionnaire
```

## Usage

```tsx
import { Questionnaire } from '@/components/fetaui/questionnaire'

const questions = [{ id: 'kind', title: 'What kind of change is this?', choices: [{ value: 'bug', label: 'Bug fix' }] }]

export function Example() {
  return <Questionnaire questions={questions} onComplete={run} />
}
```

## API

| Prop | Type | Default |
|---|---|---|
| questions | Question[] | required |
| header | steps, select, progress, count, card | steps |
| title | string |  |
| value, defaultValue | QuestionnaireAnswers | {} |
| onValueChange | (answers) => void |  |
| step, defaultStep | number | 0 |
| onStepChange | (step) => void |  |
| hostLabel | string |  |
| shortcuts | letters, numbers, switch |  |
| validation | lock, report | lock |
| errorMessage | string |  |
| foldAnswers | boolean | false |
| restored | boolean | false |
| onCancel | () => void |  |
| onComplete | (answers) => void |  |
| nextLabel, submitLabel, backLabel | string |  |
| hint | string |  |
| animated | boolean | true |

## When to use

- To gather a few structured answers in sequence, for example before an agent runs.
- Keep one question per step, three to five choices, and a written answer only when the list cannot cover it.

## When not to use

- For long forms: use Field and Fieldset.
- For a single choice on a page: use Radio.

## Accessibility

- Choices are native radios or checkboxes in a group labelled by the question.
- Focus moves to the new question title after Next.
- Errors are announced and linked with aria-describedby.
- Conditional choices disable rather than disappear, so the order stays stable.

## Motion

- The tray and actions stay still while the body trades questions: old up 12, new from below 12, 280 ms spring.
- Back reverses over 240 ms.
- Selecting lifts the choice with an ink ring over 160 ms. A shortcut presses its key for 80 ms.
- The step pill stretches over 220 ms. The error note opens over 200 ms with no shake.
- With reduced motion, questions cross fade and the ring is instant.