Skip to content
Mosaic
On this page

Radio

A set of choices where one is picked. Radio.Group holds the value, typed from what you pass. Each choice is a bare Radio.Item, or a Radio.Card laid out as an Item row with media, a label and a description.

Use for

  • picking one option from a short list
  • a choice shown as selectable cards, such as a plan or a provider
  • grouping choices under headings, with Radio.Section

Practices

GuidancePractice
DoPass name to Radio.Group when it sits in a <form>. Without one the radios do not submit.
DoGive every Radio.Item and Radio.Card a value, so the group can tell it is checked.
DoLabel a bare Radio.Item with a Field; a Radio.Card is labelled by its Radio.Label.
Don’tUse it for a long list of options. Use Select instead.

API reference

Radio.Group

A div with role="radiogroup" that holds the value and name for every radio inside it.

Slot: cl-radio-group

PropTypeDescription
valueValueThe picked value, when controlled. Any type; compared with Object.is.
defaultValueValueThe picked value on mount, when uncontrolled.
onValueChange(value: Value) => voidCalled with the picked value.
namestringThe form field name. Without it the radios are left out of form submission.
disabledbooleanDisables every radio.
layoutRadioLayoutstack gives each choice a row. grid fits as many columns of cards as fit.Default: 'stack'

Radio.Item

A native input type="radio" with a drawn indicator. The ref goes to the input. Inside a Field it takes its id, label and state from the field.

Slot: cl-radio

PropTypeDescription
valueunknownThe value it picks. A non-string value is sent to the form as JSON.
size'sm' | 'md'sm or md.Default: 'md'

Radio.Section

A titled set of choices inside a group, as a fieldset. Its radios still share the group value and arrow keys.

Slot: cl-radio-section

PropTypeDescription
labelReact.ReactNodeThe section heading, rendered as its legend.
layoutRadioLayoutstack or grid, for the choices inside it.Default: 'stack'

Radio.Card

A choice laid out as an Item row: a label around a visually hidden radio, so a click anywhere picks it. Carries data-checked and data-disabled.

Slot: cl-radio-card

PropTypeDescription
valueunknownThe value it picks.
disabledbooleanDisables this card.Default: false

Radio.Media

Item.Media, for the leading icon or image of a card.

Slot: cl-item-media

Radio.Content

Item.Content, for the label and description of a card.

Slot: cl-item-content

Radio.Label

Item.Label. Names the radio of its card.

Slot: cl-item-label

Radio.Description

Item.Description. Describes the radio of its card.

Slot: cl-item-description

Examples

Cards in a group

TSX
<Radio.Group name='provider' value={provider} onValueChange={setProvider}>
  <Radio.Card value='okta'>
    <Radio.Content>
      <Radio.Label>Okta workforce</Radio.Label>
    </Radio.Content>
  </Radio.Card>
</Radio.Group>