# 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

- Do: Pass `name` to `Radio.Group` when it sits in a `<form>`. Without one the radios do not submit.
- Do: Give every `Radio.Item` and `Radio.Card` a `value`, so the group can tell it is checked.
- Do: Label a bare `Radio.Item` with a `Field`; a `Radio.Card` is labelled by its `Radio.Label`.
- Don't: Use 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`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` |  | The picked value, when controlled. Any type; compared with `Object.is`. |
| `defaultValue` | `Value` |  | The picked value on mount, when uncontrolled. |
| `onValueChange` | `(value: Value) => void` |  | Called with the picked value. |
| `name` | `string` |  | The form field name. Without it the radios are left out of form submission. |
| `disabled` | `boolean` |  | Disables every radio. |
| `layout` | `RadioLayout` | `'stack'` | `stack` gives each choice a row. `grid` fits as many columns of cards as fit. |

### 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`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` |  | The value it picks. A non-string value is sent to the form as JSON. |
| `size` | `'sm' \| 'md'` | `'md'` | `sm` or `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`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `React.ReactNode` |  | The section heading, rendered as its `legend`. |
| `layout` | `RadioLayout` | `'stack'` | `stack` or `grid`, for the choices inside it. |

### 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`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` |  | The value it picks. |
| `disabled` | `boolean` | `false` | Disables this card. |

### 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>
```

## Related

- [Item](/docs/components/item.md)
- [Field](/docs/components/field.md)
- [Select](/docs/components/select.md)
- [Checkbox](/docs/components/checkbox.md)
