---
title: "Questionnaire"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/questionnaire"
source: "https://opsinjs.pensievelabs.org/docs/components/questionnaire.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-input"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["survey", "assessment", "phq", "screening form"]
governedBy: ["health/index", "safety-review", "high-stakes-moments"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="questionnaire"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured: the hairline, the title ink and the muted progress ink all sit on whatever ground the host provides.&#x22;,
  &#x22;Nobody has listened to the aria-live progress readout, so whether 'Question 2 of 3' on every focus move helps a reader or talks over them is unheard.&#x22;,
  &#x22;The refusal to score binds only the shell: nothing stops a product wiring a running total into its own controls, and no lint on consumer code catches it.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="questionnaire" unbuilt="false" importPath="@/components/ui/questionnaire" />

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

```tsx
<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 [#examples]

<ComponentPreview name="questionnaire" />

### A set of questions [#a-set-of-questions]

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

<ComponentPreview name="questionnaire-a-set-of-questions" kind="example" align="start" />

### Showing progress [#showing-progress]

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

<ComponentPreview name="questionnaire-showing-progress" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A set of questions the product owns, read as one group and answered in order.&#x22;,
  &#x22;A short form that needs one accessible name, a progress readout and one completion signal, with the product supplying each control.&#x22;,
  &#x22;The questions of an instrument the product licenses and scores itself, every clinical decision kept on its side.&#x22;,
]"
  avoid="[
  { case: &#x22;One question with one answer, such as a single rating or a yes or no. A set of one needs no shell.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;A set of symptoms collected as a multi-select grid rather than a sequence of separate questions.&#x22;, instead: &#x22;symptom-picker&#x22; },
]"
/>

## Clinical meaning [#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](../health/safety-review.mdx) 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](../health/two-colour-axes.mdx) forbids the mix.

**Thresholds.** The product, always. opsinjs ships no instrument, default question, option, threshold or interpretation text, and [Safety review](../health/safety-review.mdx) is why an instrument's wording and scoring stay with its licensee.

## Accessibility [#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`.

<KeyboardTable
  name="questionnaire"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves to the next control in the set&#x22;,
    notes: &#x22;No tab stop of its own. Entering a question updates the readout.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves to the previous control&#x22;,
    notes: &#x22;Same in reverse. The title and the readout are not focusable.&#x22;,
  },
  {
    keys: &#x22;Return&#x22;,
    action: &#x22;Submits the set, which the shell turns into onComplete&#x22;,
    notes: &#x22;Default navigation is cancelled, so Return never reloads the form.&#x22;,
  },
  {
    keys: &#x22;Arrow keys, Space&#x22;,
    action: &#x22;Belong to the control in focus&#x22;,
    notes: &#x22;The shell captures neither. Each key is the product control's contract.&#x22;,
  },
]"
/>

<ContrastReport component="questionnaire" />

## Props interface [#props-interface]

<PropsTable name="QuestionnaireProps" />

`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 [#data-attributes]

<DataAttributesTable
  name="questionnaire"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part, always&#x22;,
    value: &#x22;questionnaire, questionnaire-title, questionnaire-progress, questionnaire-question, questionnaire-prompt, questionnaire-control&#x22;,
  },
  {
    attribute: &#x22;data-question-index&#x22;,
    condition: &#x22;On every question list item, always&#x22;,
    value: &#x22;The question's zero-based position in the questions array&#x22;,
  },
]"
/>
