Skip to main content
Digitaltableteur

Design system components

SelectOption

Typed option child for composing Select choices declaratively; Select reads its value, label, disabled and text children into its own listbox and never mounts the option element.

Status: stable. Group: form. Markdown version: /design-system/components/select-option.md

When to use

SelectOption is the typed option primitive for Select children. Use it when declarative children are clearer than the options array. Select converts each SelectOption into an entry in its own listbox and reads only value, label, disabled and string or number children; className, data-* and other option attributes are dropped, and element children fall back to label. A value="" option is lifted out of the list and its label shown as the placeholder text.

When not to use

  • Do not render SelectOption outside Select; on its own it renders a bare option element, which only works inside a native select.
  • Do not rely on className, data-* or rich element children on SelectOption inside Select; only value, label, disabled and string children are read.

Look-alikes

  • Select: Use the Select options array for ordinary flat data; use SelectOption children for explicit declarative composition.

Props

SelectOption props
PropTypeDefaultDescriptionRequired
valuestringnoneNo description in the contract.Yes
labelstringnoneNo description in the contract.Yes
disabledbooleanfalseNo description in the contract.No
childrenReactNodenoneNo description in the contract.No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

SelectOption keyboard behaviour
KeyBehaviour
GeneralKeyboard belongs to Select: its listbox handles ArrowDown, ArrowUp, Enter, Space, Escape and type-ahead; SelectOption adds no key handling.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

SelectOption rules
LevelRuleHow it is checked
MUSTARIA: Render only as a child of Select, which maps it to an option in its own listbox; outside Select it renders a bare option element, which only works inside a native select.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTEvery documented keyboard interaction works as specified.Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.
SHOULDUse the Select options array for ordinary flat data; use SelectOption children for explicit declarative composition.Not stated in the contract.
SHOULDGive a placeholder option value=""; Select removes it from the list and shows its label as the placeholder text, so disabled on it has no effect.Not stated in the contract.
SHOULD NOTDo not render SelectOption outside Select; standalone option elements have no useful interaction semantics.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { SelectOption } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/forms exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-select-option>; see the custom elements manifest.

Links