Questionnaire

InstallCopy Anchor Link

pnpm exec vegastack-design verify questionnaire

pnpm dlx shadcn@4.21.0 add @vegastack/questionnaire

UsageCopy Anchor Link

Declare the collection once. Passing it to Questionnaire as items is what lets progress, the navigation actions and the answer shortcuts render correctly on the server, before any measurement happens on the client.

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

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

<Questionnaire items={items} onSubmit={handleSubmit}>
  <QuestionnaireProgress />
  <QuestionnaireItem name="direction" required>
    <QuestionnaireTitle>What should we prototype next?</QuestionnaireTitle>
    <QuestionnaireDescription>
      Choose a direction or write your own.
    </QuestionnaireDescription>
    <QuestionnaireChoices>
      <QuestionnaireChoice value="delegation">Delegation</QuestionnaireChoice>
      <QuestionnaireChoice value="questions">
        Question prompts
      </QuestionnaireChoice>
      <QuestionnaireInput
        aria-label="Another answer"
        placeholder="Type another answer…"
      />
    </QuestionnaireChoices>
    <QuestionnaireError />
  </QuestionnaireItem>
  <QuestionnaireActions>
    <QuestionnairePrevious />
    <QuestionnaireSkip />
    <QuestionnaireNext />
    <QuestionnaireSubmit />
  </QuestionnaireActions>
</Questionnaire>;

The root is a real <form>, so the answers arrive as FormData — get for a single answer, getAll for a multiple item.

function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  const answers = new FormData(event.currentTarget);
  // answers.get("direction"), answers.getAll(...) for multiple items.
}

AnatomyCopy Anchor Link

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

Questionnaire owns the ordered items, the active item, the answer state, validation, progress and navigation. The page, card, dialog or drawer around it owns close and cancellation behaviour, persistence, transport and branching.

ExamplesCopy Anchor Link

CompositionCopy Anchor Link

Each QuestionnaireItem is a <fieldset> and its QuestionnaireTitle is the <legend>, so a question is a real group whichever chrome you wrap it in. Only the active item is rendered — the rest are hidden and inert.

Server RenderingCopy Anchor Link

Pass items and the active item, progress, actions and answer shortcuts are all server-rendered. Without it the flow still works, but the first paint has to wait for the client to discover how many questions there are.

Multiple SelectionCopy Anchor Link

multiple on an item turns its choices into checkboxes and its answer into an array. Read it with FormData.getAll(name).

Freeform AnswerCopy Anchor Link

Compose QuestionnaireInput inside QuestionnaireChoices when the reader may supply an answer you did not list. It is one more option in the same group: filling it clears the fixed choices, and picking a fixed choice clears it. Always give it an accessible name — a placeholder is not a label.

Explicit SkipCopy Anchor Link

Add QuestionnaireSkip when an optional item may be left unanswered on purpose. onStatusChange reports "unanswered" | "answered" | "skipped", so "deliberately skipped" is a value you can store rather than an absence you have to guess at.

ShortcutsCopy Anchor Link

shortcuts="letters" or "numbers" assigns a key to each answer and renders it in the choice's shortcut slot. The engine also puts the key on aria-keyshortcuts, so it is announced rather than merely drawn.

Custom ValidationCopy Anchor Link

Combine controlled navigation with an external schema — Zod here — to return to an invalid item and present its error. invalid on the item drives aria-invalid and reveals QuestionnaireError, which is role="alert" only while it is showing.

ControlledCopy Anchor Link

item plus onItemChange hands the active item to the host, which is what lets a second control — a checkpoint label, a router, a saved draft — read the same value.

ResumeCopy Anchor Link

defaultItem restores the saved position and defaultChecked / defaultValue restore the saved answers. A native <button type="reset"> returns the form to exactly that state, and onReset is where you tell the reader it happened.

Conditional ItemsCopy Anchor Link

Mark an item disabled — in the items collection and on the item itself — when an earlier answer makes it irrelevant. Navigation steps over it and progress stops counting it, so the reader never lands on a question that does not apply.

Navigation StateCopy Anchor Link

Every navigation part exposes its own state — disabled, visible, status and the Enter shortcut — so you can hold Next until the question is answered, or restyle it from data-status.

Custom ProgressCopy Anchor Link

QuestionnaireProgress takes a render prop with { current, first, last, total }. Render whatever you like inside it; the engine keeps the role="progressbar", the value attributes and the polite announcement on the element you return.

Animated ItemsCopy Anchor Link

Animate the active item and leave progress and navigation stationary — the eye should follow the question, not the chrome. data-active:motion-enter-up is the system's fade-and-rise arrival, and base.css collapses it under prefers-reduced-motion.

CardCopy Anchor Link

Compose with Card slots while keeping the question's semantics: render the title through render={<CardTitle />} and give the item an aria-labelledby pointing at it, so the fieldset is still named by its question.

DialogCopy Anchor Link

Inside a Dialog, cancellation and dismissal stay host-owned: DialogClose is not a Questionnaire part, and closing the dialog is not the same as answering the question.

UnstyledCopy Anchor Link

The behaviour comes from @shadcn/react/questionnaire. Mount those parts directly when the flow has to look like something else entirely; the styled components above are that engine plus our token chrome and nothing more.

API ReferenceCopy Anchor Link

QuestionnaireCopy Anchor Link

Everything else a <form> accepts — onSubmit, onReset, noValidate, className, ref — passes through.

QuestionnaireItemCopy Anchor Link

QuestionnaireChoiceCopy Anchor Link

QuestionnaireInputCopy Anchor Link

QuestionnaireProgressCopy Anchor Link

QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext, QuestionnaireSubmitCopy Anchor Link

QuestionnaireActions, QuestionnaireTitle, QuestionnaireDescription, QuestionnaireChoices, QuestionnaireChoiceDescription and QuestionnaireError add no props of their own — each accepts everything the underlying element accepts, plus render where the engine exposes one.

AccessibilityCopy Anchor Link

• QuestionnaireItem renders a <fieldset> and QuestionnaireTitle renders its <legend>, so a screen reader announces the question before every answer inside it. Descriptions and active errors are associated with the current item, and invalid items and answer controls expose aria-invalid.
• Fixed choices are native radios and checkboxes, so arrow keys, Space and grouping all behave the way the platform already taught the reader. The real control is an opacity-0 input stretched over the card, which is why the card itself wears the accent/50 background tint — not a cue on something invisible — as the focus affordance. Its border never changes colour on focus (FOC-1, FOC-6, FOC-14).
• QuestionnaireInput, the free-text answer field, is text entry: focus darkens its border subtly (border-ring/50, easing in over 150ms) and paints no fill — FOC-14's text-entry exception (MK 2026-09-27). An invalid answer keeps its destructive border while focused.
• QuestionnaireProgress is a named role="progressbar" with aria-live="polite", so a step change is announced at a comfortable pace rather than interrupting (A11Y-3).
• QuestionnaireError is role="alert" only while the item is invalid, and hidden otherwise — an alert for destructive content rendered after mount, never static chrome. Those two are the only live regions in the component, which is A11Y-4's one-region rule met by the engine itself.
• Navigation uses real buttons; inactive items and actions are hidden and inert. Successful navigation focuses the newly active item, and failed validation focuses an available answer control.
• Every target clears the 24px floor: the choice card and the answer input are min-h-11 (44px), and the four navigation buttons are min-h-11 on touch widths, relaxing to the Button tier at sm:.
• Always give QuestionnaireInput an accessible name with a visible label, aria-label or aria-labelledby. A placeholder is not a label.

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/questionnaire.patch. Every hunk:

• FOC-1, FOC-6 (choice) — QuestionnaireChoice drops has-[>input:focus-visible]:ring-3 and has-[>input:focus-visible]:ring-ring/50, and FOC-14 replaces has-[>input:focus-visible]:border-ring with the accent/50 background tint (has-[>input:focus-visible]:bg-linear-to-b from-accent/50 to-accent/50, laid as an image over the fill exactly as base.css lays it). The real control is an opacity-0 input stretched over the whole card, so base.css's tint paints on something invisible — the same shape input-otp's hidden input has, and the same answer: the visible card wears the cue.
• FOC-14 (choice) — data-invalid:border-destructive stays as upstream wrote it: the invalid border holds in every state, focused or not, exactly as it does on input, checkbox and select.
• FRM-4 (choice) — data-disabled:pointer-events-none is dropped, so a disabled choice stays hoverable and a Tooltip can explain it. The engine keeps the input's own disabled, so nothing becomes answerable; upstream's data-disabled:cursor-not-allowed stays.
• FOC-1, FOC-3, FOC-6, FOC-8, FOC-14, FRM-4 (input) — QuestionnaireInput takes the same treatment input.tsx takes: outline-none becomes outline-hidden (so the FOC-7 forced-colours block has an outline to repaint), focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 is removed — no ring and no glow; the focus cue is the text-entry border below — aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 becomes aria-invalid:border-destructive with its dark counterpart, held in every state, and disabled:pointer-events-none is dropped.
• FOC-14 text-entry exception (input, MK 2026-09-27) — QuestionnaireInput adds focus:not-aria-invalid:border-ring/50 with transition-[color,background-color,border-color] duration-150 ease-out: a subtle darker border that eases in, and no fill (base.css excludes text inputs from the background tint). The not-aria-invalid guard keeps the destructive border. The choice card is not text entry and keeps the tint.
• A11Y-13 — QuestionnaireError's text-destructive becomes text-destructive-text. It is the identical pair to Field's error copy, which the row names: the status fill used as text ink measures under the AA floor, and the family's -text ink clears it.
• A11Y-3, A11Y-4 — NO HUNK. Measured in @shadcn/react@0.3.1: Progress renders role="progressbar" with aria-live="polite" and aria-label="Questionnaire progress" — A11Y-3's polite status by default — and Error renders role="alert" only while the item is invalid and hidden otherwise, which is A11Y-3's "alert only for destructive content rendered after mount" and never static chrome. One region per concern, so A11Y-4's single-region rule is met by the engine; a useAnnouncer beside it would double-announce every step. questionnaire.test.tsx asserts both shapes.
• A11Y-2 — audited, NO HUNK. Every target upstream ships is already at or over the floor: the choice is min-h-11 (44px), the answer input min-h-11, and the four navigation buttons min-h-11, relaxed to the Button tier at sm:, which is 32px. Measured in questionnaire.test.tsx.
• DOC-1, DOC-2 — cn is imported from @vegastack/design, and the rest of the diff is prettier's reflow plus the registry-stamp.mjs provenance header the three-copy model needs.
• COL-24, INT-4 — hover and press come from the shared state-layer utility, a translucent foreground layer (--state-hover, --state-pressed) over whatever fill is there, so the step reads the same on every surface in both themes; selected, open and highlighted fills are bg- state-selected / bg-state-hover. Operator, Regent, 2026-10-31.
• FOC-15 — the choice card shows its radio's keyboard focus with the layer-focus tint, the same info-hue cue base.css paints. Operator, Regent, 2026-10-31.