Components
Questionnaire
The styled form shell that groups a product's own questions and shows how far through them a reader is, while scoring and interpreting nothing clinical.
Usage
pnpm dlx shadcn@latest add @opsinjs/questionnaire
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
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 /> },
]}
/>Examples
questionnaire · base base · style base-lyraOpen under the product themeA set of questions
Three invented questions under one title, each with a control the product composed.
questionnaire-a-set-of-questions · base base · style base-lyraOpen under the product themeimport { Questionnaire } from "@/components/ui/questionnaire"
function Choice({ name, options }: { name: string; options: string[] }) {
return (
<div role="radiogroup" className="flex flex-col gap-opsin-1">
{options.map((option) => (
<label
key={option}
className="inline-flex min-h-(--opsin-target-minimum,2.75rem) cursor-pointer items-center gap-opsin-2 text-opsin-body [color:var(--foreground)]"
>
<input
type="radio"
name={name}
value={option}
className="size-[1em] focus-visible:outline-ring focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)]"
/>
{option}
</label>
))}
</div>
)
}
export default function QuestionnaireASetOfQuestions() {
return (
<Questionnaire
title="Getting-ready check-in (example)"
questions={[
{
id: "sleep",
prompt: "How rested did you feel this morning?",
control: (
<Choice
name="questionnaire-set-sleep"
options={["Not much", "Somewhat", "A lot"]}
/>
),
},
{
id: "water",
prompt: "How often did you fill your water bottle today?",
control: (
<Choice
name="questionnaire-set-water"
options={["Rarely", "Sometimes", "Often"]}
/>
),
},
{
id: "note",
prompt: "Anything you would like your team to know?",
control: (
<textarea
rows={2}
className="w-full rounded-opsin-md border border-border bg-card p-opsin-2 text-opsin-body [color:var(--foreground)] focus-visible:outline-ring focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)]"
/>
),
},
]}
/>
)
}Showing progress
showProgress turns on the readout above the list. It follows focus, so entering the second question reads "Question 2 of 3".
questionnaire-showing-progress · base base · style base-lyraOpen under the product themeimport { Questionnaire } from "@/components/ui/questionnaire"
function Choice({ name, options }: { name: string; options: string[] }) {
return (
<div role="radiogroup" className="flex flex-col gap-opsin-1">
{options.map((option) => (
<label
key={option}
className="inline-flex min-h-(--opsin-target-minimum,2.75rem) cursor-pointer items-center gap-opsin-2 text-opsin-body [color:var(--foreground)]"
>
<input
type="radio"
name={name}
value={option}
className="size-[1em] focus-visible:outline-ring focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)]"
/>
{option}
</label>
))}
</div>
)
}
export default function QuestionnaireShowingProgress() {
return (
<Questionnaire
title="Weekly reflection (example)"
showProgress
questions={[
{
id: "walks",
prompt: "How often did you take a short walk this week?",
control: (
<Choice
name="questionnaire-progress-walks"
options={["Rarely", "Sometimes", "Often"]}
/>
),
},
{
id: "plan",
prompt: "How easy was it to keep to your plan?",
control: (
<Choice
name="questionnaire-progress-plan"
options={["Not easy", "Somewhat", "Very easy"]}
/>
),
},
{
id: "mood",
prompt: "How would you describe your week overall?",
control: (
<Choice
name="questionnaire-progress-mood"
options={["Quiet", "Mixed", "Busy"]}
/>
),
},
]}
/>
)
}When to use it
Use it when
- A set of questions the product owns, read as one group and answered in order.
- A short form that needs one accessible name, a progress readout and one completion signal, with the product supplying each control.
- The questions of an instrument the product licenses and scores itself, every clinical decision kept on its side.
Do not use it when
- One question with one answer, such as a single rating or a yes or no. A set of one needs no shell.Use
fieldinstead. - A set of symptoms collected as a multi-select grid rather than a sequence of separate questions.Use
symptom-pickerinstead.
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, because 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, which is the line Safety review draws 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, and Two colour axes forbids the mix.
Thresholds. The product, always. opsinjs ships no instrument, default question, option, threshold or interpretation text, and Safety review is why an instrument's wording and scoring stay with its licensee.
Accessibility
The audit gave every prompt a stable id and put each control in a role="group" named by that prompt through aria-labelledby. It also gave the default demo's free-text control an aria-label, so it is no longer unnamed. A check on every commit keeps the chrome neutral, with no status colour, category colour, colour literal, ramp step or px type size. Title, prompts and readout are semantic type steps.
Residual items.
- 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. - Every contrast pair against the host ground is unmeasured, and so is
forced-colors: active.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves to the next control in the set | No tab stop of its own. Entering a question updates the readout. |
| Shift+Tab | Moves to the previous control | Same in reverse. The title and the readout are not focusable. |
| Return | Submits the set, which the shell turns into onComplete | Default navigation is cancelled, so Return never reloads the form. |
| Arrow keys, Space | Belong to the control in focus | The shell captures neither. Each key is the product control's contract. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from QuestionnaireProps in registry/bases/base/questionnaire.tsx.
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.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every inner part, always | questionnaire, questionnaire-title, questionnaire-progress, questionnaire-question, questionnaire-prompt, questionnaire-control |
| data-question-index | On every question list item, always | The question's zero-based position in the questions array |