# 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
- Page: https://www.digitaltableteur.com/design-system/components/select-option
- Contract: https://www.digitaltableteur.com/contracts/v1/SelectOption.contract.json

## 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

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `value` | `string` | none | No description in the contract. | Yes |
| `label` | `string` | none | No description in the contract. | Yes |
| `disabled` | `boolean` | `false` | No description in the contract. | No |
| `children` | `ReactNode` | none | No 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

| Key | Behaviour |
| --- | --- |
| General | Keyboard 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.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST | ARIA: 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. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The 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. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | Every documented keyboard interaction works as specified. | Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2. |
| MUST | A human completed an end-to-end accessibility review of this component. | Manual review, last on 2026-11-04. |
| SHOULD | Use the Select options array for ordinary flat data; use SelectOption children for explicit declarative composition. | Not stated in the contract. |
| SHOULD | Give 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 NOT | Do 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

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/SelectOption.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/select-option.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.