Choice group
<forma-choice-group>
Semantic single-choice option cards with a bold primary label and optional supporting text, backed by native radios.
- Authoring tag
<forma-choice-group>- Category
- Selection and choice
- Behavior owner
- Native HTML
- Canonical source
patterns/choice-group.html
Purpose
A choice group asks one question and offers a short list of mutually exclusive answers, each shown as a full-width card with a label and an optional description. It is a native fieldset with a legend and one input type="radio" per forma-choice label; all radios share a name. Forma hides the native radio visually, draws its own round indicator, and fills the selected card. The browser owns selection, arrow keys, required validation, submission and reset. The same forma-choice card is reused with checkboxes by Multi-choice and with media by Image choice.
Use when
- One answer must be picked from two to about seven options.
- Each option benefits from a sentence of explanation.
- The question is part of a form, survey or setup flow where options should be compared in a vertical list.
Avoid when
- The options are short modes that fit side by side: use Segmented control.
- Several answers may be picked: use Multi-choice.
- The options are ordered agreement, frequency or rating steps: use Ordinal scale.
- The answer is yes/no and Unanswered must stay distinct: use Binary choice.
- There are many options or they come from data: use Select or Combobox.
Behavior to know
- Each card is the whole hit target and is at least 3.25rem tall.
- Selection is shown by a filled dot in the indicator plus an accent border and surface change, not by color alone.
- The native radio stays in the card, topmost for hit-testing, and carries focus, name and state.
- Cards stack vertically at every width; long text wraps inside the card. Cards grow with wrapped text after resizing or text enlargement, keeping the marker centered beside the whole content block.
Basic example
The smallest correct markup: the canonical pattern from patterns/choice-group.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal choice group
Rendered from the canonical pattern file.
<forma-choice-group class="forma-component-tag">
<fieldset class="forma-choice-group">
<legend class="forma-choice-group__legend">Which environment is most representative?</legend>
<label class="forma-choice">
<input type="radio" name="environment" value="cloud" required>
<span class="forma-choice__content">
<strong>Cloud</strong>
<span>Primarily hosted cloud infrastructure.</span>
</span>
</label>
<label class="forma-choice">
<input type="radio" name="environment" value="hybrid">
<span class="forma-choice__content">
<strong>Hybrid</strong>
<span>Cloud and on-premises infrastructure.</span>
</span>
</label>
<label class="forma-choice">
<input type="radio" name="environment" value="on-premises">
<span class="forma-choice__content">
<strong>On-premises</strong>
<span>Primarily locally hosted infrastructure.</span>
</span>
</label>
</fieldset>
</forma-choice-group>
Click or tap the code once to select all of it, then copy.
Examples
Validation error
The user tried to continue without answering. The application renders a Validation message after the options and links it to the fieldset with aria-describedby, so it is announced with the group. Forma does not detect the error; the native required constraint and the application's message do.
<forma-choice-group class="forma-component-tag">
<fieldset class="forma-choice-group" aria-describedby="choice-group-validation-error-message">
<legend class="forma-choice-group__legend">How should we contact you about this order?</legend>
<label class="forma-choice">
<input type="radio" name="choice-group-validation-error-contact" value="email" required>
<span class="forma-choice__content"><strong>Email</strong><span>Order updates to the address on your account.</span></span>
</label>
<label class="forma-choice">
<input type="radio" name="choice-group-validation-error-contact" value="sms">
<span class="forma-choice__content"><strong>Text message</strong><span>Delivery-day updates only. Carrier rates may apply.</span></span>
</label>
<label class="forma-choice">
<input type="radio" name="choice-group-validation-error-contact" value="none">
<span class="forma-choice__content"><strong>No updates</strong><span>Check the order page yourself.</span></span>
</label>
<p class="forma-validation-message" id="choice-group-validation-error-message">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Choose how we should contact you before continuing.
</p>
</fieldset>
</forma-choice-group>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Long options on a phone
A consent-style question with long primary labels and descriptions at phone width. Every card spans the width and grows taller as its text wraps.
What changes at narrow widths
- Cards are full-width grid rows; text wraps inside the card and the card grows in height, so nothing overflows at 320px.
- The indicator stays vertically centred at the inline start of each card, beside the wrapped text.
- Each card is a large touch target (at least 3.25rem tall, full width); tapping anywhere on it selects the option.
- There are no breakpoints: the vertical list is already the narrow layout, and portrait or landscape only changes line lengths.
<forma-choice-group class="forma-component-tag">
<fieldset class="forma-choice-group">
<legend class="forma-choice-group__legend">What should happen to your shared files when you leave the workspace?</legend>
<label class="forma-choice">
<input type="radio" name="choice-group-mobile-long-options-files" value="transfer">
<span class="forma-choice__content"><strong>Transfer ownership to the workspace administrator</strong><span>Collaborators keep access. You lose access on your last day.</span></span>
</label>
<label class="forma-choice">
<input type="radio" name="choice-group-mobile-long-options-files" value="export">
<span class="forma-choice__content"><strong>Export a copy to my personal account, then delete</strong><span>Collaborators lose access after 30 days.</span></span>
</label>
</fieldset>
</forma-choice-group>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | radio | — | Single choice uses radios. (Checkbox cards are documented on Multi-choice.) |
name | input | string | — | Shared by every radio in the group; unique per group on the page. |
value | input | string | "on" | Submitted value for the chosen option. |
required | input | boolean | absent | Native constraint on the group; set it on one radio. |
checked | input | boolean | absent | Initial selection. |
disabled | input | boolean | absent | Makes an option unselectable and dims its card. |
aria-describedby | fieldset | id | — | Links guidance or a validation message to the whole group. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-choice-group | Block class | — | The fieldset: border and padding reset, options stacked in a grid with a small gap. |
.forma-choice-group__legend | Element class | — | The question, set in bold at body size above the options. |
.forma-choice | Block class | — | One option card (a label): bordered, padded to make room for the drawn indicator, whole card clickable. Checked cards get an accent border and secondary surface. |
.forma-choice__content | Element class | — | Grid holding the bold primary label and the optional supporting text. |
.forma-choice__media | Element class | — | Media frame used by the forma-choice--media variant; see Image choice. |
.forma-choice--exclusive | Modifier class | — | Dashed card border marking an exclusive option such as "None of these" in a checkbox set; see Multi-choice. The application enforces exclusivity. |
.forma-choice--media | Modifier class | — | Two-column card with a 4:3 media frame beside the text, and no drawn indicator; stacks at 44rem and below. See Image choice. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves into the group (to the checked option, or the first) and out of it; the group is one tab stop. |
| Arrow Down / Arrow Right | Selects the next enabled option, wrapping at the end (native radio behavior). |
| Arrow Up / Arrow Left | Selects the previous enabled option. |
| Space | Selects the focused option when none is selected. |
| Event | Description |
|---|---|
input / change | Native events from the newly selected radio. |
invalid | Native event fired on a required radio when the form is submitted with no selection. |
Form behavior
Submits the selected option's name=value. required blocks submission until one option is chosen; form reset restores the initial selection.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Unselected | no checked attribute | Empty round indicator and primary surface. |
| Selected | :checked | Filled dot in the indicator, accent border and secondary surface. Forced-colors mode uses Highlight and HighlightText. |
| Focus | :focus-visible on the radio | Two-tone focus ring around the card. |
| Disabled | disabled attribute | Card at reduced opacity with a not-allowed cursor; skipped by arrow keys. |
| Invalid (application) | validation message linked with aria-describedby | Forma has no invalid styling on the group; the application renders the message. |
Accessibility
Forma provides
- Keeps native radios in each card, so role, group, position and arrow-key selection come from the platform.
- Makes the entire card the label, so the whole card is the click and touch target.
- Shows selection with a shape change (filled dot) in addition to border and surface color.
- Uses Highlight/HighlightText for the selected card in forced-colors mode and restates inner colors so text stays legible.
Your application supplies
- Write the question in the legend; keep option labels short and put detail in the supporting text.
- Link validation or guidance to the fieldset with aria-describedby.
- Explain disabled options in their description.
- Keep option order meaningful but never let position imply a score or recommendation.
Responsive behavior
- The group is a single-column grid at every width; cards fill the available width.
- Primary and supporting text wrap inside the card; cards grow in height and never force horizontal overflow.
- No breakpoints for plain cards. The
forma-choice--mediavariant collapses from two columns to one at 44rem and below.
Motion
- Card background, border and text color change by perceptual interpolation (
--forma-motion-perceptual-duration, about 120ms). Nothing moves, and the selected state is applied immediately. - Under
prefers-reduced-motion: reducethe global reduction shortens the color transition to effectively instant.
Usage guidance
Do
- Use a question in the legend and answers as parallel phrases.
- Preselect only when a safe default exists; otherwise leave all unchecked and use required.
Avoid
- Nesting interactive elements such as links or buttons inside an option card; the whole card is a label.
- Relying on the accent color alone to show the selected option in custom themes.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.