Questionnaire
A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions. Dependency-free with native form serialization.
Installation#
pnpm dlx shadcn@latest add @davinciui/questionnaireUsage#
Questionnaire owns the ordered items, active item, answer state, validation, progress, and navigation. The containing page, card, dialog, or drawer owns close and cancellation behavior, persistence, transport, and branching.
Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│ ├── QuestionnaireTitle
│ ├── QuestionnaireDescription
│ ├── QuestionnaireChoices
│ │ ├── QuestionnaireChoice
│ │ └── QuestionnaireInput
│ └── QuestionnaireError
└── QuestionnaireActions
├── QuestionnairePrevious
├── QuestionnaireSkip
├── QuestionnaireNext
└── QuestionnaireSubmitMultiple Selection#
Freeform Answer#
Explicit Skip#
Shortcuts#
Controlled#
Conditional Items#
Custom Validation#
Custom Progress#
Card#
Composition#
Use the following composition to build a Questionnaire:
Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│ ├── QuestionnaireTitle
│ ├── QuestionnaireDescription
│ ├── QuestionnaireChoices
│ │ └── QuestionnaireChoice
│ │ └── QuestionnaireChoiceLabel
│ ├── QuestionnaireInput
│ └── QuestionnaireError
└── QuestionnaireActions
├── QuestionnairePrevious
├── QuestionnaireSkip
├── QuestionnaireNext
└── QuestionnaireSubmitAPI Reference#
| Prop | Type | Default |
|---|---|---|
itemsItem collection for server-rendered progress, order, actions, and shortcuts. | readonly QuestionnaireItemDefinition[] | — |
itemControlled active item name. | string | — |
defaultItemInitially active item. Restored on form reset. | string | first enabled |
onItemChangeFires when navigation requests a different item. | (item: string) => void | — |
shortcutsAssigns a scoped shortcut key to each enabled fixed choice. | "letters" | "numbers" | — |
noValidateDisables native constraint UI; validation uses QuestionnaireError. | boolean | true |
nameItem identifier and native form field name. Must be unique per root. | string | — |
requiredRequires an answer; hides Skip for the item. | boolean | false |
multipleRenders fixed choices as checkboxes. Read with FormData.getAll(). | boolean | false |
disabledOmits the item from progress, navigation, validation, and submission. | boolean | false |
invalidMarks the item invalid from an external validator. | boolean | false |
onStatusChangeObserves answer-status changes for an item. | (status: "unanswered" | "answered" | "skipped") => void | — |
valueChoice answer value submitted under the item name. | string | — |
renderCustom render target for Progress and navigation actions with their state. | (props, state) => ReactElement | — |
aria-labelAccessible name for the freeform input. A placeholder is not a label. | string | "Another answer" |
Accessibility#
Native fieldsets, legends, radios, checkboxes, and inputs provide semantics; inactive items are hidden and the active fieldset receives focus on navigation. Errors use role alert and aria-invalid, but the fieldset focus outline is suppressed.
Motion#
Steps switch instantly through the hidden attribute; only short color transitions on choices and buttons plus an unconfigured width transition on the progress bar animate. The file contains no prefers-reduced-motion detection.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

