Checkbox cards

API and Development

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

CheckboxCards drives Radix CheckboxCards with an options array. Each entry renders a CheckboxCard with value, label, optional description, and layout flags. The group supports controlled value / onValueChange, indicatorPosition, indicatorHidden, horizontal (lays cards out in a single row), disabled, and readOnly (shows lock affordance and blocks changes).

CheckboxCards

Name	Type	Default	Description
`legend`	`LocalizedMessage`	—	Group name, rendered in the Fieldset `legend`; it is the group's accessible name.
`children`	`ReactNode`	—	{@link CheckboxCard } items.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`defaultValue`	`readonly string[]`	—	Initial selected values when uncontrolled, and the values a native form reset restores.
`description`	`LocalizedMessage`	—	Group helper copy linked through `aria-describedby`.
`disabled`	`boolean`	`false`	Disables every card through native `fieldset[disabled]`.
`error`	`LocalizedMessage`	—	Group error copy. When set, it is linked through `aria-describedby` and every card input is `aria-invalid` with the invalid indicator.
`form`	`string`	—	Id of the form that owns the inputs when they sit outside it.
`indicatorPosition`	`CheckboxCardsIndicatorPosition`	`CheckboxCardsIndicatorPosition.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 card input. Omit to keep the cards out of form submission.
`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 cards, 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 cards. Use it with `onBlur` to track whether the group was touched.
`onValueChange`	`((value: string[], details: ChangeDetails<CheckboxCardsValueChangeReason>) => void)`	—	Called for every selection change, including controlled mode and form reset. `InputChange` is cancelable; `FormReset` is not, because the browser restores the inputs either way.
`orientation`	`CheckboxCardsOrientation`	`CheckboxCardsOrientation.Vertical`	Main-axis layout of the cards.
`readOnly`	`boolean`	`false`	Makes every card read only: selected state shows and cards stay focusable, but activation changes nothing. Each card shows a lock glyph opposite its indicator.
`ref`	`Ref<HTMLFieldSetElement>`	—	Ref to the host `fieldset`.
`value`	`readonly string[]`	—	Controlled selected values. `undefined` on the first render is uncontrolled.

Storybook

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

DefaultOpens in a new tab

Option fields (CheckboxCardProps)

Name	Type	Default	Description
`value`	`string`	`required`	Stable id.
`label`	`LocalizedMessage \| DisplayValue`	`required`	Primary line. Copy from formatMessage, or data from toDisplayValue.
`description`	`ReactNode`	`—`	Secondary line.
`indicatorPosition`	`"left" \| "right"`	`—`	Overrides group default when supported.
`indicatorHidden`	`boolean`	`—`	Per-card indicator visibility.
`readOnly`	`boolean`	`false`	Lock icon when group is read-only.

Example

CheckboxCard

A card-based pattern for more descriptive or visual options.

Basic Card

Use for simple selections with an optional description.

With Description

Provide added context or benefits.

Disabled Cards

Disable options based on conditions.

Right Indicators

Indicators can also appear on the right-side of the checkbox card for elements aligned to the right-hand side of the page.

Hidden Indicators

Hide the checkbox indicator when you do not want a visible state.

CheckboxCards

Manage multiple cards with controlled or uncontrolled selection.

Multiple Selection

Allow selecting more than one option.

Controlled Selection

Control selection state externally for complex flows.

Disabled Group

Disable all cards when selection is unavailable.

Right-Aligned Indicators

Place indicators on the right for alternate layouts.

Checkbox Cards / Usage

Checkbox Cards / Accessibility

On this page

CheckboxCards

Storybook

Option fields (CheckboxCardProps)

Right-Aligned Indicators

Checkbox cards

API and Development

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

CheckboxCards

Name	Type	Default	Description
`legend`	`LocalizedMessage`	—	Group name, rendered in the Fieldset `legend`; it is the group's accessible name.
`children`	`ReactNode`	—	{@link CheckboxCard } items.
`className`	`string`	—	@deprecated Pass layout through enum props and shipped parts. Request a missing case via find-pattern.
`defaultValue`	`readonly string[]`	—	Initial selected values when uncontrolled, and the values a native form reset restores.
`description`	`LocalizedMessage`	—	Group helper copy linked through `aria-describedby`.
`disabled`	`boolean`	`false`	Disables every card through native `fieldset[disabled]`.
`error`	`LocalizedMessage`	—	Group error copy. When set, it is linked through `aria-describedby` and every card input is `aria-invalid` with the invalid indicator.
`form`	`string`	—	Id of the form that owns the inputs when they sit outside it.
`indicatorPosition`	`CheckboxCardsIndicatorPosition`	`CheckboxCardsIndicatorPosition.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 card input. Omit to keep the cards out of form submission.
`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 cards, 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 cards. Use it with `onBlur` to track whether the group was touched.
`onValueChange`	`((value: string[], details: ChangeDetails<CheckboxCardsValueChangeReason>) => void)`	—	Called for every selection change, including controlled mode and form reset. `InputChange` is cancelable; `FormReset` is not, because the browser restores the inputs either way.
`orientation`	`CheckboxCardsOrientation`	`CheckboxCardsOrientation.Vertical`	Main-axis layout of the cards.
`readOnly`	`boolean`	`false`	Makes every card read only: selected state shows and cards stay focusable, but activation changes nothing. Each card shows a lock glyph opposite its indicator.
`ref`	`Ref<HTMLFieldSetElement>`	—	Ref to the host `fieldset`.
`value`	`readonly string[]`	—	Controlled selected values. `undefined` on the first render is uncontrolled.

Storybook

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

DefaultOpens in a new tab

Option fields (CheckboxCardProps)

Name	Type	Default	Description
`value`	`string`	`required`	Stable id.
`label`	`LocalizedMessage \| DisplayValue`	`required`	Primary line. Copy from formatMessage, or data from toDisplayValue.
`description`	`ReactNode`	`—`	Secondary line.
`indicatorPosition`	`"left" \| "right"`	`—`	Overrides group default when supported.
`indicatorHidden`	`boolean`	`—`	Per-card indicator visibility.
`readOnly`	`boolean`	`false`	Lock icon when group is read-only.