Questionnaire

Install

pnpm dlx shadcn@latest add @vegastack/questionnaire

Usage

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.
}

Anatomy

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.

Examples

Composition

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 Rendering

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 Selection

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

Freeform Answer

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 Skip

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.

Shortcuts

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 Validation

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.

Controlled

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.

Resume

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 Items

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 State

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 Progress

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 Items

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.

Card

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.

Dialog

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.

Unstyled

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 Reference

Questionnaire

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

QuestionnaireItem

QuestionnaireChoice

QuestionnaireInput

QuestionnaireProgress

QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext, QuestionnaireSubmit

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.

Accessibility

• 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's own border — not an outline on something invisible — is the focus affordance (FOC-1, FOC-6).
• 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't

Deviations

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 keeps has-[>input:focus-visible]:border-ring. The real control is an opacity-0 input stretched over the whole card, so base.css's outline paints on something invisible — the same shape input-otp's hidden input has, and the same answer: the visible card's border is the affordance.
• FOC-5 (choice) — data-invalid:border-destructive becomes not-has-[>input:focus-visible]:data-invalid:border-destructive, so focus outranks the invalid tint 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-5, 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 becomes focus:border-ring/70 — the 70% text-entry tint, on :focus so it fires for mouse and keyboard alike — aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 becomes not-focus:aria-invalid:border-destructive with its dark counterpart, and disabled:pointer-events-none is dropped.
• 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.