Prepared Docs

Overview

RadioCardGroup is the single-select counterpart to CheckboxCardGroup: mutually exclusive options presented as cards so operators can read description copy before committing. Optimize for decision quality, not minimal height. Typical dispatch contexts: plan tiers, routing modes, escalation policies, first-time configuration selections where a misread means a different runtime behavior.

When to use

Two to four options where short comparison copy (description, price, feature bullet) helps the operator choose.
Onboarding or upgrade flows where the context is one-time and the decision deserves space.
Tappable cards that hold up on narrow dispatch panes as well as wide viewports.

When not to use

Many similar options—vertical Radio lists or Select reduce height.
Multi-select—use CheckboxCardGroup.
Options that change frequently or load asynchronously—consider Combobox with descriptions.

Content guidelines

Parallel titles and one-sentence descriptions per card. Localize with formatMessage.
Call out irreversible or paid consequences in description text, not in fine print below the control.
Keep the description scoped to "what this option means"—not marketing copy that competes with the title.

Behavior and states

Defaults. Preselect the safest or most common choice when one exists. When no default is appropriate, force explicit selection with validation.
Disabled cards. Surface the reason in description copy; never rely on the gray styling alone.
Layout. Horizontal only when cards remain legible at the narrow breakpoint; otherwise stack vertically.

Best practices

Limit to a small visible set. Link to docs for edge-case configurations.
Keep the selection indicator in a consistent position across cards (always leading or always trailing).
Match the card widths so the set reads as a row of peers.

Don't

Hide required choices below the fold without summarizing what's missing at the form level.
Use cards when a single sentence suffices. Prefer Radio for compact single-select.
Mix visual emphasis between cards (don't make one card look primary unless the product actually treats it as the default).

Accessibility

The entire card is activatable via pointer or keyboard; focus lands on the card; descriptions tie to the input via aria-describedby where supported. See Accessibility for the full contract.

Radio for compact single-select.
Checkbox cards for multi-select analog.
Segmented control for short mode toggles.

Radio / Accessibility

Radio Cards / API and Development

Overview

When to use

Two to four options where short comparison copy (description, price, feature bullet) helps the operator choose.
Onboarding or upgrade flows where the context is one-time and the decision deserves space.
Tappable cards that hold up on narrow dispatch panes as well as wide viewports.

When not to use

Many similar options—vertical Radio lists or Select reduce height.
Multi-select—use CheckboxCardGroup.
Options that change frequently or load asynchronously—consider Combobox with descriptions.

Content guidelines

Parallel titles and one-sentence descriptions per card. Localize with formatMessage.
Call out irreversible or paid consequences in description text, not in fine print below the control.
Keep the description scoped to "what this option means"—not marketing copy that competes with the title.

Behavior and states

Defaults. Preselect the safest or most common choice when one exists. When no default is appropriate, force explicit selection with validation.
Disabled cards. Surface the reason in description copy; never rely on the gray styling alone.
Layout. Horizontal only when cards remain legible at the narrow breakpoint; otherwise stack vertically.

Best practices

Limit to a small visible set. Link to docs for edge-case configurations.
Keep the selection indicator in a consistent position across cards (always leading or always trailing).
Match the card widths so the set reads as a row of peers.

Don't

Hide required choices below the fold without summarizing what's missing at the form level.
Use cards when a single sentence suffices. Prefer Radio for compact single-select.
Mix visual emphasis between cards (don't make one card look primary unless the product actually treats it as the default).

Accessibility

The entire card is activatable via pointer or keyboard; focus lands on the card; descriptions tie to the input via aria-describedby where supported. See Accessibility for the full contract.