Radio cards

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

RadioCards wraps Radix RadioCards with mutually exclusive selection. Pass options with value, label, and optional description and disabled. Layout, indicator and read-only state belong to the group: horizontal lays out cards in one row, showIndicator hides radio dots, indicatorPosition moves the dot, disabled and readOnly apply to every card. An option's own disabled disables just that card.

RadioCards

Name	Type	Default	Description
`legend`	`LocalizedMessage`	—	Group name, rendered in the Fieldset `legend`; it is the radiogroup's accessible name.
`children`	`ReactNode`	—	{@link RadioCardsItem } children.
`className`	`string`	—	Classes on the host `fieldset`. Put overrides in `@layer chroma.overrides`.
`defaultValue`	`string \| null`	—	Initial selected value when uncontrolled, and the value a native form reset restores.
`description`	`LocalizedMessage`	—	Group helper copy linked through `aria-describedby`.
`disabled`	`boolean`	—	Disables every radio through native `fieldset[disabled]`.
`error`	`LocalizedMessage`	—	Group error copy. When set, the radiogroup is `aria-invalid`, the error is linked through `aria-describedby`, and every radio paints its invalid ring.
`form`	`string`	—	Id of the form that owns the radios when they sit outside it.
`indicatorPosition`	`RadioCardsIndicatorPosition`	`RadioCardsIndicatorPosition.Start`	Where each card draws its indicator.
`legendVisibility`	`FieldsetLegendVisibility`	—	Hides the legend visually; the copy stays in the `legend`. Defaults to visible.
`name`	`string`	—	Form field name shared by every radio. Defaults to a generated id.
`onBlur`	`FocusEventHandler<HTMLElement>`	—	Called once when focus leaves the whole group for somewhere outside it, such as the next field. It is not called when focus moves between radios, so a form library validates on blur once per visit.
`onFocus`	`FocusEventHandler<HTMLElement>`	—	Called once when focus enters the group from outside it. It is not called when focus moves between radios. Use it with `onBlur` to track whether the group was touched.
`onValueChange`	`((value: string \| null, details: ChangeDetails<RadioGroupValueChangeReason>) => void)`	—	Called for every selection change, including controlled mode and form reset. `InputChange` is cancelable; `FormReset` is not, because the browser restores the radios either way.
`orientation`	`RadioCardsOrientation`	`RadioCardsOrientation.Vertical`	Card layout. Defaults to {@link RadioCardsOrientation.Vertical}.
`readOnly`	`boolean`	`false`	Makes every card read only: the checked card still shows and cards stay focusable, but activation changes nothing. The radiogroup is `aria-readonly` and each card shows a lock glyph opposite its indicator.
`ref`	`Ref<HTMLFieldSetElement>`	—	Ref to the host `fieldset`.
`required`	`boolean`	—	Marks the group required: the legend ends with Label's decorative `*`, the radiogroup is `aria-required`, and every radio carries native `required`.
`requiredHint`	`LocalizedMessage`	—	Form-level copy that explains the required marker, shown under the legend.
`value`	`string \| null`	—	Controlled selected value. `undefined` on the first render is uncontrolled; `null` selects nothing.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Example

Basic RadioCards

Use for card-based selection with rich content.

RadioCards with Descriptions

Add descriptions to provide additional context for each option.

RadioCards with Right Indicator

Position the radio indicator on the right side.

RadioCards without Indicator

Hide radio indicators for minimal visual presentation.

Controlled RadioCards

Control RadioCards selection programmatically.

Disabled RadioCards

Disable the entire card group or specific options.

Disabling a single option

Set disabled on an option to take just that card out of the group. It can't be focused or selected, and arrow-key navigation skips it. The group's disabled still disables every card.

Radio vs RadioCards

Choose the appropriate component based on context and content needs.

Use Radio when:

Options are simple labels without additional context
Space is limited and compact presentation is needed
Traditional form patterns are appropriate
Quick selection without extensive information

Use RadioCards when:

Options require descriptions or additional context
Visual prominence and card-based presentation is desired
Rich content helps users make informed decisions
Card layout better matches the design aesthetic

Comparison Example

Radio Group

RadioCards Group

Radio Cards / Usage

Radio Cards / Accessibility

On this page

RadioCards with Descriptions

RadioCards with Right Indicator

RadioCards without Indicator

Controlled RadioCards

Disabled RadioCards

Disabling a single option

Radio cards

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

RadioCards

Name	Type	Default	Description
`legend`	`LocalizedMessage`	—	Group name, rendered in the Fieldset `legend`; it is the radiogroup's accessible name.
`children`	`ReactNode`	—	{@link RadioCardsItem } children.
`className`	`string`	—	Classes on the host `fieldset`. Put overrides in `@layer chroma.overrides`.
`defaultValue`	`string \| null`	—	Initial selected value when uncontrolled, and the value a native form reset restores.
`description`	`LocalizedMessage`	—	Group helper copy linked through `aria-describedby`.
`disabled`	`boolean`	—	Disables every radio through native `fieldset[disabled]`.
`error`	`LocalizedMessage`	—	Group error copy. When set, the radiogroup is `aria-invalid`, the error is linked through `aria-describedby`, and every radio paints its invalid ring.
`form`	`string`	—	Id of the form that owns the radios when they sit outside it.
`indicatorPosition`	`RadioCardsIndicatorPosition`	`RadioCardsIndicatorPosition.Start`	Where each card draws its indicator.
`legendVisibility`	`FieldsetLegendVisibility`	—	Hides the legend visually; the copy stays in the `legend`. Defaults to visible.
`name`	`string`	—	Form field name shared by every radio. Defaults to a generated id.
`onBlur`	`FocusEventHandler<HTMLElement>`	—	Called once when focus leaves the whole group for somewhere outside it, such as the next field. It is not called when focus moves between radios, so a form library validates on blur once per visit.
`onFocus`	`FocusEventHandler<HTMLElement>`	—	Called once when focus enters the group from outside it. It is not called when focus moves between radios. Use it with `onBlur` to track whether the group was touched.
`onValueChange`	`((value: string \| null, details: ChangeDetails<RadioGroupValueChangeReason>) => void)`	—	Called for every selection change, including controlled mode and form reset. `InputChange` is cancelable; `FormReset` is not, because the browser restores the radios either way.
`orientation`	`RadioCardsOrientation`	`RadioCardsOrientation.Vertical`	Card layout. Defaults to {@link RadioCardsOrientation.Vertical}.
`readOnly`	`boolean`	`false`	Makes every card read only: the checked card still shows and cards stay focusable, but activation changes nothing. The radiogroup is `aria-readonly` and each card shows a lock glyph opposite its indicator.
`ref`	`Ref<HTMLFieldSetElement>`	—	Ref to the host `fieldset`.
`required`	`boolean`	—	Marks the group required: the legend ends with Label's decorative `*`, the radiogroup is `aria-required`, and every radio carries native `required`.
`requiredHint`	`LocalizedMessage`	—	Form-level copy that explains the required marker, shown under the legend.
`value`	`string \| null`	—	Controlled selected value. `undefined` on the first render is uncontrolled; `null` selects nothing.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Example

Basic RadioCards

Use for card-based selection with rich content.

RadioCards with Descriptions

Add descriptions to provide additional context for each option.

RadioCards with Right Indicator

Position the radio indicator on the right side.

RadioCards without Indicator

Hide radio indicators for minimal visual presentation.

Controlled RadioCards

Control RadioCards selection programmatically.

Disabled RadioCards

Disable the entire card group or specific options.

Disabling a single option

Set disabled on an option to take just that card out of the group. It can't be focused or selected, and arrow-key navigation skips it. The group's disabled still disables every card.

Radio vs RadioCards

Choose the appropriate component based on context and content needs.

Use Radio when: