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

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.