---
title: "SymptomPicker"
description: "A multi-select over a symptom list the product supplies, recording which options a reader ticks and never checking, triaging or interpreting them."
url: "https://opsinjs.pensievelabs.org/docs/components/symptom-picker"
source: "https://opsinjs.pensievelabs.org/docs/components/symptom-picker.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-input"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["symptoms", "how are you feeling", "symptom checker"]
governedBy: ["health/index", "safety-review"]
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="symptom-picker"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured. This component sets no surface of its own, so the box fill, the check glyph and the field border sit on the host's ground.&#x22;,
  &#x22;Nothing stops a product wiring the returned values into a checker or a triage flow, and no lint rule on a consumer's own code holds that line.&#x22;,
  &#x22;Nobody has listened to this in a screen reader, so whether the filter's changing result count is announced as rows appear and disappear is unheard.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="symptom-picker" unbuilt="false" importPath="@/components/ui/symptom-picker" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

```tsx
import { SymptomPicker } from "@/components/ui/symptom-picker"
```

```tsx
<SymptomPicker
  label="Which of these apply to you right now?"
  value={selected}
  onValueChange={setSelected}
  options={[
    { value: "example-one", label: "Example symptom one" },
    { value: "example-two", label: "Example symptom two" },
    { value: "example-three", label: "Example symptom three" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="symptom-picker" />

### Choosing from a list [#choosing-from-a-list]

Driven by `options`. The labels are fictional placeholders, because opsinjs ships
no symptom list and an example must never be mistaken for a real vocabulary.

<ComponentPreview name="symptom-picker-choosing-from-a-list" kind="example" align="start" />

### Filtering a long list [#filtering-a-long-list]

With `searchable` on, the filter narrows the visible rows by a match on their
label, and the ticked values stay ticked as it narrows.

<ComponentPreview name="symptom-picker-with-search" kind="example" align="start" />

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

<WhenToUse
  use="[
  &#x22;Recording which items from a product-owned list apply, where more than one can apply and the caller wants the set back.&#x22;,
  &#x22;A short list the reader scans in place before a consultation, stored against the reader's own record.&#x22;,
  &#x22;A longer product-owned list, with searchable on so the reader filters the rows by typing rather than scrolling.&#x22;,
]"
  avoid="[
  { case: &#x22;There is one thing to confirm, a single yes or no. A whole picker for one option is read twice.&#x22;, instead: &#x22;checkbox&#x22; },
  { case: &#x22;Exactly one option applies and the rest exclude it, so the choice is one-of-many rather than any-of-many.&#x22;, instead: &#x22;radio-group&#x22; },
  { case: &#x22;The reader describes something in their own words rather than picking from a list the product wrote.&#x22;, instead: &#x22;textarea&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** These are the values a reader ticked from the list you supplied.
Nothing about what an option means, how the ticked set reads together, or what
happens next.

**Never read as.** A symptom checker, a triage or a diagnosis. Feeding the
returned array into a rule that reaches a clinical conclusion moves the product
onto the pathway [Safety review](../health/safety-review.mdx) describes.

**Colour axis.** Neither. A selection is not a clinical level, so the component
carries no `data-status` and no `data-category`. The ticked state travels as a
check shape and a quiet fill, so it survives greyscale.

**Thresholds.** The consuming product owns them. opsinjs ships no symptom list,
option labels or default text, because a controlled vocabulary is product
specific, and [Health](../health/index.mdx) is why the picker records and never
interprets.

## Accessibility [#accessibility]

Each option is a real checkbox with its icon `aria-hidden`, the pressable row
floors at `--opsin-target-minimum` in rem, and axe, target-size and 320px reflow
checks were clean. The audit fixed one gap under SC 4.1.3 Status Messages: with
`searchable` on, the count change sat in no live region, so a screen reader never
heard the result count or that nothing matched. A persistent visually hidden
`role="status"` region now announces the filtered count.

**Residual items.**

* `forced-colors` stays unchecked.
* The group and filter names are forwarded only as `aria-label`, with no persistent visible label. A required `label` prop keeps the group from being nameless, but a visible label is a recommended enhancement, deferred for one repair across the whole set.

<KeyboardTable
  name="symptom-picker"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves to the next control, the filter field or an option&#x22;,
    notes: &#x22;Each checkbox is its own tab stop. A disabled option is skipped.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves to the previous control&#x22;,
    notes: &#x22;The same stops in reverse, then out of the picker.&#x22;,
  },
  {
    keys: &#x22;Space&#x22;,
    action: &#x22;Ticks or unticks the focused option&#x22;,
    notes: &#x22;An option is a checkbox, so Space activates it. Focus stays put.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Does nothing on an option&#x22;,
    notes: &#x22;The primitive cancels it, so a picker never submits its form.&#x22;,
  },
  {
    keys: &#x22;Typing&#x22;,
    action: &#x22;Filters the list, in the filter field only&#x22;,
    notes: &#x22;Present only when searchable is set. It changes no ticked value.&#x22;,
  },
]"
/>

<ContrastReport component="symptom-picker" />

## Props interface [#props-interface]

<PropsTable name="SymptomPickerProps" />

`options` is the product's vocabulary and the whole of what the picker draws, so
an empty array renders nothing and warns in development. `value` and
`onValueChange` make this controlled, with no selection state of its own. A value
matching no option is kept and named by a warning. `label` is required, because a
group with no accessible name is a defect.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="symptom-picker"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part, always&#x22;,
    value: &#x22;symptom-picker, symptom-picker-search, symptom-picker-option, symptom-picker-option-label, symptom-picker-empty&#x22;,
  },
  {
    attribute: &#x22;data-checked, data-unchecked&#x22;,
    condition: &#x22;On an option, one or the other, by whether it is ticked&#x22;,
    value: &#x22;Stamped by Base UI's Checkbox primitive&#x22;,
  },
  {
    attribute: &#x22;data-disabled&#x22;,
    condition: &#x22;On an option the product marked disabled&#x22;,
    value: &#x22;The row drops to the muted ink and takes no pointer or key&#x22;,
  },
]"
/>
