Selection and choice

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

Canonical

Minimal choice group

Rendered from the canonical pattern file.

Which environment is most representative?
HTML · Minimal choice group Raw HTML for HTML · Minimal choice group
<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

Scenario

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.

How should we contact you about this order?

Choose how we should contact you before continuing.

HTML · Validation error Raw HTML for HTML · Validation error
<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.

Scenario

Selected plan with an unavailable option

The current plan is preselected, and one option is natively disabled because the application has decided it is not available for this account. The card dims and shows a not-allowed cursor, and its description says why.

Support plan
HTML · Selected plan with an unavailable option Raw HTML for HTML · Selected plan with an unavailable option
<forma-choice-group class="forma-component-tag">
  <fieldset class="forma-choice-group">
    <legend class="forma-choice-group__legend">Support plan</legend>
    <label class="forma-choice">
      <input type="radio" name="choice-group-unavailable-option-plan" value="standard" checked>
      <span class="forma-choice__content"><strong>Standard</strong><span>Business-hours response within one working day.</span></span>
    </label>
    <label class="forma-choice">
      <input type="radio" name="choice-group-unavailable-option-plan" value="priority">
      <span class="forma-choice__content"><strong>Priority</strong><span>Response within four hours, every day.</span></span>
    </label>
    <label class="forma-choice">
      <input type="radio" name="choice-group-unavailable-option-plan" value="dedicated" disabled>
      <span class="forma-choice__content"><strong>Dedicated engineer</strong><span>Unavailable: requires an Enterprise contract.</span></span>
    </label>
  </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.

Mobile example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Long options on a phone Raw HTML for HTML · Long options on a phone
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinputradio—Single choice uses radios. (Checkbox cards are documented on Multi-choice.)
nameinputstring—Shared by every radio in the group; unique per group on the page.
valueinputstring"on"Submitted value for the chosen option.
requiredinputbooleanabsentNative constraint on the group; set it on one radio.
checkedinputbooleanabsentInitial selection.
disabledinputbooleanabsentMakes an option unselectable and dims its card.
aria-describedbyfieldsetid—Links guidance or a validation message to the whole group.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-choice-groupBlock class—The fieldset: border and padding reset, options stacked in a grid with a small gap.
.forma-choice-group__legendElement class—The question, set in bold at body size above the options.
.forma-choiceBlock 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__contentElement class—Grid holding the bold primary label and the optional supporting text.
.forma-choice__mediaElement class—Media frame used by the forma-choice--media variant; see Image choice.
.forma-choice--exclusiveModifier 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--mediaModifier 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.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves into the group (to the checked option, or the first) and out of it; the group is one tab stop.
Arrow Down / Arrow RightSelects the next enabled option, wrapping at the end (native radio behavior).
Arrow Up / Arrow LeftSelects the previous enabled option.
SpaceSelects the focused option when none is selected.
Events
EventDescription
input / changeNative events from the newly selected radio.
invalidNative 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

Choice group states
StateHow it is expressedPresentation
Unselectedno checked attributeEmpty round indicator and primary surface.
Selected:checkedFilled dot in the indicator, accent border and secondary surface. Forced-colors mode uses Highlight and HighlightText.
Focus:focus-visible on the radioTwo-tone focus ring around the card.
Disableddisabled attributeCard at reduced opacity with a not-allowed cursor; skipped by arrow keys.
Invalid (application)validation message linked with aria-describedbyForma 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--media variant 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: reduce the 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.