Questionnaire

Preview

Installation

pnpm dlx shadcn@latest add @opsinjs/questionnaire

Usage

import { Questionnaire } from "@/components/ui/questionnaire"

<Questionnaire
  title="Weekly check-in"
  showProgress
  onComplete={handleComplete}
  questions={[
    { id: "rest", prompt: "How rested did you feel this week?", control: <RestControl /> },
    { id: "plan", prompt: "How easy was it to keep to your plan?", control: <PlanControl /> },
  ]}
/>

When to use it

Clinical meaning

Asserts. Two things about the form, not the person: these questions, in this order, and how far through them you are. The progress count is an ordinal of position, drawn as plain text.

Never read as. A score, a screening result, a diagnosis or triage. A questionnaire on screen means the product has asked, not that it has assessed. The shell draws whatever wording it is handed, so a product that edits or misgrades a licensed instrument owns that hazard. Regulatory context draws that line around a presentation layer.

Colour axis. Neither. The shell states no level and names no category, so it carries neither data-status nor data-category. The two colour axes forbids the mix.

Thresholds. The product, always. opsinjs ships no instrument, no default question, no option, no threshold and no interpretation text. Evidence and references is why an instrument's wording and scoring stay with its licensee.

Anatomy

Examples

A set of questions

Three invented questions under one title, each with a control the product composed.

Showing progress

showProgress turns on the readout above the list. It follows focus, so entering the second question reads "Question 2 of 3".

Content guidelines

Write every question and option in the reader's own words. Render a licensed instrument exactly as licensed, because the shell cannot tell an edited item from the original. Keep the title a short name, not an instruction.

Accessibility

Audited against WCAG 2.2 AA, in a source pass and a rendered pass. The audit is author-run, not independent, and clinical review is pending.

Fixed in this pass.

• Every prompt carries a stable id, and each control sits in a role="group" named by that prompt through aria-labelledby.
• The default demo's free-text control gained an aria-label, so it is no longer unnamed.

Neutral chrome, checked on every commit.

• No status colour, no category colour, no colour literal and no ramp step.
• No px type size. Title, prompts and readout are semantic type steps.

Known and deferred.

• The shell cannot name a product's own control node, so a product that passes a bare input still labels it, with the per-question group supplying context.
• The title is the form's aria-labelledby, drawn as a styled div, because the shell cannot know the host page's heading level. A visible heading on the product's side is recommended.
• The progress line is aria-live="polite", announced as focus moves. It may read as chatty, which is a tuning question for the product.

Not measured. Every contrast pair against the host ground, and forced-colors: active.

Data attributes

API reference

onComplete is told that the reader finished and nothing else, because the shell reads no answer. Submit is cancelled even when it is omitted. An empty questions array renders nothing and warns in development, as does a duplicate id or a missing title.

Related

• Field is one question with one answer. A set of one needs no shell.
• SymptomPicker collects symptoms as a multi-select grid, not a sequence.
• LogSheet records repeated readings over time. A questionnaire gathers a one-off set and keeps none.