Questionnaire
A multi-step form that asks one question at a time, with single-choice, multiple-choice, freeform and skippable questions.
A questionnaire shows one question at a time and moves through them in order. It fits anywhere a short series of questions has to be answered before something can continue: an agent asking clarifying questions, onboarding, a survey, an intake form, a setup flow.
It owns the ordered items, the active item, answer state, validation, progress
and navigation. The page, card, dialog or drawer around it owns closing and
cancelling, persistence, transport and branching. The behaviour comes from the
headless @shadcn/react/questionnaire package; this component draws its
answers as arene's choice cards and its actions as arene buttons.
Installation
Needs the arene setup first. Also adds Button, Checkbox, Field, Input, Kbd, Label, Radio Group, Separator and Stack.
Install the packages it imports:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation, and paste states.ts from the same page,
which hides the native inputs and draws the focus ring and the disabled dim.
It also needs interop.css, which sizes the checkmark, and the
lib/focus-visible.ts helper, which tells a card whether its focus came from
the keyboard.
Add Button, Checkbox, Radio Group, Field, Input and Kbd. The actions render the button and the freeform answer renders the input. The rest reuse the exported style maps of the other four: the checkbox or radio box and its tick or dot, the field's choice card and error text, and the keycap of the shortcut.
Paste the focus-visible helper and the component into your project.
Change the @/ imports if your project uses different aliases.
Usage
Questionnaire renders a native form, so the answers are read with FormData.
Each item's name is the field name of its answers.
Composition
Every item stays mounted. The inactive ones are hidden and inert, and each
action shows only when it applies: Previous after the first item, Skip on an
optional item, Next before the last item and Submit on it.
QuestionnaireActions lays them out with Previous at the start and the rest at
the end.
Give Questionnaire the same items array that you render as items and
choices. With it, the item order, progress, the visible actions and the
answer shortcuts are in the server-rendered HTML. Without it, the questionnaire
reads them from the rendered parts after hydration.
Multiple selection
multiple turns an item's choices into checkboxes. Read the answers with
FormData.getAll().
Freeform answer
Put a QuestionnaireInput beside the choices when the reader can give another
answer. In a single-choice item, typing replaces the selected choice and
selecting a choice replaces the typed answer. Give the input an accessible name
with aria-label or a visible label; a placeholder is not one.
Explicit skip
QuestionnaireSkip records that an optional item was left unanswered on
purpose. A skipped item is absent from FormData, so use onStatusChange on
the item when the host needs to tell a skip from a missing answer.
Shortcuts
shortcuts="letters" gives each enabled choice a key from A to Z, and
shortcuts="numbers" from 1 to 9. Pressing a key selects the answer
without moving to the next item.
Custom validation
The questionnaire validates the active item before it moves forward and every
enabled item on submit. A required item needs an answer, and an optional one
needs an answer or a skip. For a rule across items, set invalid on the item,
pass the message to QuestionnaireError, and move the controlled item back
to it.
Controlled
Pass item and onItemChange to keep the active item in host state.
Resume
Restore a saved draft with defaultItem on the root, defaultChecked on
choices and defaultValue on the input. A type="reset" button restores those
defaults, the starting item and the skip state.
Conditional items
A disabled item leaves the flow: it is skipped by navigation and left out of
progress, validation and the submitted answers.
Navigation state
The actions stay enabled by default, so pressing Next on an unanswered item
shows its error. To disable one until the item is answered, track the status
with the item's onStatusChange and pass disabled to the action:
Set disabled on the action, not on the element its render returns. The
action reads the prop to drop its Enter shortcut, so a button disabled only
in render keeps aria-keyshortcuts="Enter".
Custom progress
QuestionnaireProgress reads Question 1 of 3 by default. Pass render to
draw something else from current and total. It keeps its progressbar
role and values either way.
Animated items
An inactive item is display: none, so a keyframe animation on the item
replays each time it becomes active. Animate the entry only; the item leaving
is hidden at once.
Card
Wrap a Card in the questionnaire to give the flow a header and a footer tray. The progress can sit in the header's action slot, since it reads the questionnaire rather than an item.
Dialog
Inside a Dialog, closing cancels the whole flow and belongs to the dialog, while Skip answers one item. Keep the two apart.
Accessibility
- Each item is a
fieldsetandQuestionnaireTitleis itslegend. If you render the title as another element, give it anidand pass that to the item'saria-labelledby. - The description and the active error are linked to the item with
aria-describedby. An invalid item and its answers carryaria-invalid. - Choices are native radios and checkboxes, visually hidden inside the card that draws them, so the whole card is the label.
- Progress is a named
progressbarwith its current, minimum and maximum values. - Moving to an item focuses it, and a failed validation focuses its first answer.
| Key | Behaviour |
|---|---|
Tab | Moves between the answers and the visible actions |
ArrowUp / ArrowDown | Moves between the answers. A radio is selected as it is reached |
ArrowLeft | Goes to the previous item, outside a radio or a text field |
ArrowRight | Goes to the next item once the active one is answered or skipped, outside a radio or a text field |
Space | Selects a radio, toggles a checkbox or presses the focused action |
Enter | Continues from a selected choice or a filled input |
Command/Ctrl + Enter | Validates and continues from anywhere in the questionnaire, or submits the last item |
Shortcut keys and arrow navigation pause while you type in a text field.
Calling preventDefault() in the root's onKeyDown turns the key handling off.
API reference
Every part wraps the @shadcn/react part of the same name and accepts its
props; the headless Questionnaire reference
has the full list. Every part also takes xstyle, className and style.
Pass render to replace a part's element, except on Questionnaire and
QuestionnaireItem, which always render a form and a fieldset. A function
render receives the part's state as its second argument.
Questionnaire
| Prop | Type | Default |
|---|---|---|
items | readonly QuestionnaireItemDefinition[] | — |
item | string | — |
defaultItem | string | first enabled item |
onItemChange | (item: string) => void | — |
shortcuts | "letters" | "numbers" | — |
noValidate | boolean | true |
noValidate keeps the browser's own validation bubbles away, so errors come
from QuestionnaireError. A questionnaire cannot sit inside another form.
QuestionnaireItem
| Prop | Type | Default |
|---|---|---|
name | string | required |
required | boolean | false |
multiple | boolean | false |
disabled | boolean | false |
invalid | boolean | false |
onStatusChange | (status: QuestionnaireItemStatus) => void | — |
The title's spacing depends on whether the item has a description, which the
item finds by looking for a QuestionnaireDescription among its direct
children.
QuestionnaireChoice
| Prop | Type | Default |
|---|---|---|
value | string | required |
checked | boolean | — |
defaultChecked | boolean | false |
disabled | boolean | false |
onChange | ChangeEventHandler<HTMLInputElement> | — |
Its children are the answer's label. Add a QuestionnaireChoiceDescription
after the label for a second, muted line. The card draws the radio or checkbox
and the shortcut key itself.
QuestionnaireInput
| Prop | Type | Default |
|---|---|---|
value | string | — |
defaultValue | string | — |
type | QuestionnaireInputType | "text" |
disabled | boolean | false |
onChange | ChangeEventHandler<HTMLInputElement> | — |
It renders an Input, so it dims while disabled and shows the invalid ring when its item fails validation.
QuestionnaireError
Hidden until its item fails validation. Its children replace the default message.
Navigation actions
QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext and
QuestionnaireSubmit render a Button and take its
variant and size. QuestionnaireSubmit is type="submit"; the others are
type="button". Children replace the default label.
| Prop | Type | Default |
|---|---|---|
variant | ButtonVariant | "outline" for Previous and Skip, else "default" |
size | ButtonSize | "default" |
The render state holds visible, disabled, shortcut and the active item's
status.
questionnaireStyles
The style map behind the component, exported so you can apply the same styles to other elements.
| Key | What it is |
|---|---|
root | The form's column and gap |
progress | The progress text |
item | The item's column and gap |
title | The question's type |
description | The muted line under the question |
choices | The grid of answers |
choice | The answer card, fieldStyles.card laid out as a row |
choiceChecked | The card's selected edge, fieldStyles.cardChecked |
choiceFocused | The card's keyboard-focus ring, fieldStyles.cardFocused |
choiceLabel | The column that holds an answer's label and description |
choiceDescription | An answer's second line |
input | The freeform field, the same as inputStyles.base |
error | The validation message, the same as fieldStyles.error |
actions | The three-column grid of actions |
Data attributes
The headless parts write their state as data attributes. A boolean is present while it is true, and the others carry their value.
| Part | State attributes |
|---|---|
| the root | data-current, data-total, data-first, data-last, data-shortcuts |
| the progress | data-current, data-total, data-first, data-last |
| each item | data-active, data-status, data-required, data-multiple, data-disabled, data-invalid |
| the answer grid | data-shortcuts |
| each answer card | data-type, data-checked, data-unchecked, data-disabled, data-invalid, data-shortcut |
| the input | data-filled, data-empty, data-disabled, data-invalid |
| the error | data-invalid |
| each action | data-visible, data-hidden, data-disabled, data-shortcut, data-status |
data-shortcuts holds the shortcuts mode and a card's data-shortcut its
key. An action's data-shortcut is Enter on Next and Submit while they are
visible and enabled, and its data-status is the active item's status.
| Attribute | On |
|---|---|
data-slot="questionnaire" | the form |
data-slot="questionnaire-progress" | the progress |
data-slot="questionnaire-item" | each item |
data-slot="questionnaire-title" | the title |
data-slot="questionnaire-description" | the description |
data-slot="questionnaire-choices" | the answer grid |
data-slot="questionnaire-choice" | each answer card |
data-slot="questionnaire-choice-description" | an answer's second line |
data-slot="questionnaire-input" | the freeform input |
data-slot="questionnaire-error" | the error |
data-slot="questionnaire-actions" | the action row |
data-slot="questionnaire-previous" | the Previous button |
data-slot="questionnaire-skip" | the Skip button |
data-slot="questionnaire-next" | the Next button |
data-slot="questionnaire-submit" | the Submit button |
data-variant, data-size | each action, from Button |