Questionnaire

A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions.

Installation

bash

npx shadcn-vue@latest add questionnaire

Usage

vue

<script setup lang="ts">
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/ui/questionnaire";

const items = [
  { name: "direction", required: true },
  { name: "timing", required: true },
];

function handleSubmit(event: Event) {
  event.preventDefault();

  const answers = new FormData(event.target as HTMLFormElement);
  console.log(Object.fromEntries(answers));
}
</script>

<template>
  <Questionnaire :items="items" @submit="handleSubmit">
    <QuestionnaireProgress />

    <QuestionnaireItem name="direction" required>
      <QuestionnaireTitle>What should the agent build next?</QuestionnaireTitle>
      <QuestionnaireDescription>Choose a direction.</QuestionnaireDescription>
      <QuestionnaireChoices>
        <QuestionnaireChoice value="tool-calls">Tool call timeline</QuestionnaireChoice>
        <QuestionnaireChoice value="approvals">Approval checkpoints</QuestionnaireChoice>
      </QuestionnaireChoices>
      <QuestionnaireError />
    </QuestionnaireItem>

    <QuestionnaireItem name="timing" required>
      <QuestionnaireTitle>When should work begin?</QuestionnaireTitle>
      <QuestionnaireChoices>
        <QuestionnaireChoice value="now">Start now</QuestionnaireChoice>
        <QuestionnaireChoice value="backlog">Add it to the backlog</QuestionnaireChoice>
      </QuestionnaireChoices>
      <QuestionnaireError />
    </QuestionnaireItem>

    <QuestionnaireActions>
      <QuestionnairePrevious />
      <QuestionnaireSkip />
      <QuestionnaireNext />
      <QuestionnaireSubmit />
    </QuestionnaireActions>
  </Questionnaire>
</template>

Composition

Use the following composition to build a questionnaire:

Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│   ├── QuestionnaireTitle
│   ├── QuestionnaireDescription
│   ├── QuestionnaireChoices
│   │   ├── QuestionnaireChoice
│   │   │   └── QuestionnaireChoiceDescription
│   │   └── QuestionnaireInput
│   └── QuestionnaireError
└── QuestionnaireActions
    ├── QuestionnairePrevious
    ├── QuestionnaireSkip
    ├── QuestionnaireNext
    └── QuestionnaireSubmit

Server Rendering

Pass items to server-render the active item, progress, actions, and answer shortcuts. Without it the questionnaire only learns its order once the items have mounted on the client.

Features

One question at a time, with progress, navigation, and validation handled for you
Single-choice, multiple-choice, freeform, and intentionally skipped answers
Keyboard shortcuts for choices, plus arrow key navigation between questions and answers
Declarative items for item order, conditional items, and stable shortcut assignment
Controlled navigation with v-model:item for custom validation flows
Native form reset restores the answers you marked as defaults

Multiple Selection

Use multiple for an item that accepts more than one fixed answer.

Freeform Answer

Compose QuestionnaireInput with fixed choices when the user can provide another answer.

Explicit Skip

Add QuestionnaireSkip when an optional item may be intentionally left unanswered.

Shortcuts

Assign a letter or number key to each answer with shortcuts.

Custom Validation

Combine controlled navigation with an external schema such as Zod to return to an invalid item and present its error.

Controlled

Control the active item from host state, such as returning to an invalid step.

Current checkpoint: Change scope

Resume

Restore a saved active item and default answers, then reset changes back to that saved state.

Conditional Items

Disable items that do not apply to the user's earlier answers.

Animated Items

Animate the active item while keeping progress and navigation stationary.

Card

Compose Questionnaire with Card slots while keeping the question title and description semantic.

Dialog

Compose Questionnaire inside a Dialog while keeping cancellation and dismissal host-owned.

Anatomy

Import all parts and piece them together.

vue

<script setup>
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoiceDescription,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/ui/questionnaire";
</script>

<template>
  <Questionnaire>
    <QuestionnaireProgress />
    <QuestionnaireItem>
      <QuestionnaireTitle />
      <QuestionnaireDescription />
      <QuestionnaireChoices>
        <QuestionnaireChoice>
          <QuestionnaireChoiceDescription />
        </QuestionnaireChoice>
        <QuestionnaireInput />
      </QuestionnaireChoices>
      <QuestionnaireError />
    </QuestionnaireItem>
    <QuestionnaireActions>
      <QuestionnairePrevious />
      <QuestionnaireSkip />
      <QuestionnaireNext />
      <QuestionnaireSubmit />
    </QuestionnaireActions>
  </Questionnaire>
</template>

API Reference

Questionnaire

Prop	Type	Default	Description
`items`	`QuestionnaireItemDefinition[]`	—	Declares item order, required, disabled, and the choices used for shortcuts.
`item`	`string`	—	The active item. Use with v-model:item.
`defaultItem`	`string`	—	The item shown first. Ignored when item is provided.
`shortcuts`	`"letters" \| "numbers"`	—	Assigns a keyboard shortcut to every choice.
`noValidate`	`boolean`	`true`	Set to false to run native constraint validation on answered items.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the form.

Event	Description
`update:item`	The active item changed. Payload: string.
`submit`	Every item is valid. Payload: Event. Call event.preventDefault() to handle it yourself.
`reset`	The form was reset. Payload: Event. Call event.preventDefault() to keep the answers.

Slot	Description
`default`	Progress, items, and actions.

QuestionnaireProgress

Prop	Type	Default	Description
`as`	`AsTag \| Component`	`"div"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the progress bar.

Slot	Description
`default`	Scoped: { current, total, first, last }. Falls back to Question N of M. Renders a named progressbar either way.

QuestionnaireItem

Prop	Type	Default	Description
`name`	`string`	—	Required. The name the answer submits under.
`required`	`boolean`	`false`	Requires an answer before the questionnaire can continue.
`multiple`	`boolean`	`false`	Renders choices as checkboxes and keeps every selected answer.
`disabled`	`boolean`	`false`	Removes the item from the flow without unmounting it.
`invalid`	`boolean`	`false`	Marks the item invalid from outside, for example after schema validation.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the item.

Event	Description
`update:status`	The item status changed. Payload: "unanswered" \| "answered" \| "skipped".

Slot	Description
`default`	Scoped: { active, invalid, status }. Title, description, choices, error.

QuestionnaireTitle

Prop	Type	Default	Description
`as`	`AsTag \| Component`	`"legend"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the title.

Slot	Description
`default`	The question, rendered as a legend.

QuestionnaireDescription

Prop	Type	Default	Description
`id`	`string`	—	Overrides the generated id.
`as`	`AsTag \| Component`	`"p"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the description.

Slot	Description
`default`	Help text associated with the item through aria-describedby.

QuestionnaireChoices

Prop	Type	Default	Description
`as`	`AsTag \| Component`	`"div"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the list.

Slot	Description
`default`	QuestionnaireChoice items and an optional input.

QuestionnaireChoice

Prop	Type	Default	Description
`value`	`string`	—	Required. The submitted value.
`checked`	`boolean`	—	Controlled checked state. Use with v-model:checked.
`defaultChecked`	`boolean`	`false`	Checks the choice on mount and after a native form reset.
`disabled`	`boolean`	`false`	Disables the choice.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the choice.

Event	Description
`update:checked`	The choice was checked or cleared. Payload: boolean.
`change`	The native change event. Payload: Event.

Slot	Description
`default`	Label text and QuestionnaireChoiceDescription.

QuestionnaireChoiceDescription

Prop	Type	Default	Description
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the description.

Slot	Description
`default`	Secondary text inside a choice.

QuestionnaireInput

Prop	Type	Default	Description
`modelValue`	`string \| number`	—	Controlled value. Use with v-model.
`defaultValue`	`string \| number`	—	Fills the answer on mount and after a native reset.
`type`	`QuestionnaireInputType`	`"text"`	A text-entry type: text, email, number, tel, url, search, password, date, datetime-local, month, time, or week.
`disabled`	`boolean`	`false`	Disables the input.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the input.

Event	Description
`update:modelValue`	The value changed. Payload: string.

QuestionnaireError

Prop	Type	Default	Description
`id`	`string`	—	Overrides the generated id.
`as`	`AsTag \| Component`	`"p"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the error.

Slot	Description
`default`	Custom message. Falls back to a built-in one when omitted.

QuestionnaireActions

Prop	Type	Default	Description
`as`	`AsTag \| Component`	`"div"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the row.

Slot	Description
`default`	The navigation buttons.

QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext, QuestionnaireSubmit

Prop	Type	Default	Description
`variant`	`ButtonVariants["variant"]`	`"outline"`	The button variant. QuestionnaireSubmit defaults to `default`.
`size`	`ButtonVariants["size"]`	`"default"`	The button size.
`disabled`	`boolean`	`false`	Disables the button.
`as`	`AsTag \| Component`	`"button"`	The element or component to render as.
`asChild`	`boolean`	`false`	Render the child element instead.
`class`	`HTMLAttributes["class"]`	—	Additional classes to apply to the button.

Event	Description
`click`	The native click event. Call event.preventDefault() to stop the navigation. QuestionnaireSubmit has no click handler of its own.

Slot	Description
`default`	Button label. Defaults to "Previous", "Skip", "Next", and "Submit".

Keyboard navigation

Questionnaire builds on native radio, checkbox, input, and button behavior. Shortcuts and arrow navigation pause while you type in a text field.

Shortcut	Description
`Tab`	Moves focus between answer controls and visible actions.
`Shift` + `Tab`	Moves focus to the previous control or action.
`↓`	Moves to the next answer. Single-choice items hand this to the browser, so a radio group keeps its native roving focus.
`↑`	Moves to the previous answer. Same handover as ArrowDown: the component only steps in for checkboxes and for a text input mixed with choices.
`→`	Moves to the next question once the current one is answered or skipped, and focus is outside a radio or text entry control.
`←`	Moves to the previous question, when focus is outside a radio or text entry control.
`Space`	Selects a radio, toggles a checkbox, or activates an action.
`Enter`	Continues from a selected choice or a filled input, or activates a focused action.
`Ctrl` + `Enter`	Validates and continues from anywhere inside the questionnaire, or submits on the final item. Cmd works too.
`A`	With shortcuts="letters", selects the matching choice. Use 1 to 9 with shortcuts="numbers".

Accessibility

ARIA behavior.

QuestionnaireItem renders a fieldset with a legend, so every question is announced with its answers. Descriptions and errors are associated with the item through aria-describedby, and an invalid item exposes aria-invalid.
QuestionnaireProgress renders a named progressbar that announces the current question. Inactive items are hidden and inert, so they stay out of the tab order and the accessibility tree.
Navigation actions are real buttons. QuestionnaireSubmit submits the form, so a questionnaire keeps working with browser autofill and native form submission.
Assigned shortcut keys and available navigation are exposed through aria-keyshortcuts.
Always give QuestionnaireInput an accessible name with a visible label, aria-label, or aria-labelledby. A placeholder is not a label.

QR Code Radio Group

Questionnaire

Default

Installation

Usage

Composition

Server Rendering

Features

Multiple Selection

Freeform Answer

Explicit Skip

Shortcuts

Custom Validation

Controlled

Resume

Conditional Items

Navigation State

Custom Progress

Animated Items

Card

What should the agent work on?

What should the final handoff include?

Dialog

Anatomy

API Reference

Questionnaire

QuestionnaireProgress

QuestionnaireItem

QuestionnaireTitle

QuestionnaireDescription

QuestionnaireChoices

QuestionnaireChoice

QuestionnaireChoiceDescription

QuestionnaireInput

QuestionnaireError

QuestionnaireActions

QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext, QuestionnaireSubmit

Keyboard navigation

Accessibility