# Radio button

> Lets people choose exactly one option from a short list.

- Category: Selection and input
- API status: Stable
- Compose APIs: `RadioButton`, `RadioButtonDefaults`, `Modifier.selectableGroup`
- Interactive page: https://m3e.ljzapps.app/#components/radio-button

## When to use

Use radio buttons when all options should be visible at once and only one can apply. For long lists use a menu, and for two options consider a switch.

Wrap the group in Modifier.selectableGroup and make each row selectable with Role.RadioButton.

## Playground

The interactive page has a playground with live property controls for this component and generated code.

## Examples

### Group

```kotlin
val options = listOf("Small", "Medium", "Large")
var selected by rememberSaveable { mutableIntStateOf(1) }

Column(Modifier.selectableGroup()) {
    options.forEachIndexed { index, label ->
        Row(
            modifier = Modifier
                .fillMaxWidth()
                .selectable(
                    selected = selected == index,
                    onClick = { selected = index },
                    role = Role.RadioButton,
                ),
            verticalAlignment = Alignment.CenterVertically,
        ) {
            RadioButton(selected = selected == index, onClick = null)
            Text(label)
        }
    }
}
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `selected` | `Boolean` |  | Whether this option is selected. |
| `onClick` | `(() -> Unit)?` |  | Pass null when the row handles the click. |
| `colors` | `RadioButtonColors` | `RadioButtonDefaults.colors()` | Selected and unselected colors. |

## Guidelines

Do:
- Preselect the safest option.
- Put the label to the right of the control.

Don't:
- Do not allow deselection by tapping the selected option.
- Do not use more than seven options.

## Accessibility

- Screen readers announce the position in the group, for example 2 of 3.
- Arrow keys move the selection inside the group.

## Related components

- [Checkbox](https://m3e.ljzapps.app/docs/components/checkbox.md)
- [Segmented button](https://m3e.ljzapps.app/docs/components/segmented-button.md)
- [Menu](https://m3e.ljzapps.app/docs/components/menu.md)