Checkbox

Lets people select one or more items from a set, or turn an option on or off.

Category: Selection and input
API status: Stable
Compose APIs: Checkbox, TriStateCheckbox, CheckboxDefaults
Interactive page: https://m3e.ljzapps.app/#components/checkbox

When to use

Use checkboxes for independent choices. A parent checkbox with an indeterminate state can summarise a group of children.

Make the label part of the touch target by putting the checkbox and the text in one toggleable row, and pass null as onCheckedChange to the checkbox itself.

Playground

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

Examples

Parent with indeterminate state

val children = remember { mutableStateOf(listOf(true, false, false)) }
val parentState = when {
    children.value.all { it } -> ToggleableState.On
    children.value.none { it } -> ToggleableState.Off
    else -> ToggleableState.Indeterminate
}

Column {
    Row(Modifier.clickable { children.value = List(3) { parentState != ToggleableState.On } }, verticalAlignment = Alignment.CenterVertically) {
        TriStateCheckbox(state = parentState, onClick = null)
        Text("Select all")
    }
    children.value.forEachIndexed { index, value ->
        Row(
            Modifier.padding(start = 24.dp).toggleable(value, role = Role.Checkbox) { checked ->
                children.value = children.value.toMutableList().also { it[index] = checked }
            },
            verticalAlignment = Alignment.CenterVertically,
        ) {
            Checkbox(checked = value, onCheckedChange = null)
            Text("Option ${index + 1}")
        }
    }
}

Parameters

Name	Type	Default	Description
`checked`	`Boolean`		Whether the box is checked.
`onCheckedChange`	`((Boolean) -> Unit)?`		Pass null when a parent handles the toggle, for example Modifier.toggleable.
`enabled`	`Boolean`	`true`	Disables interaction.
`colors`	`CheckboxColors`	`CheckboxDefaults.colors()`	Box, check mark and border colors.

Guidelines

Do:

Phrase labels so that checked means yes.
Group related checkboxes.

Don't:

Do not use checkboxes for mutually exclusive choices.
Do not apply the change later than the user expects.

Accessibility

Use Role.Checkbox on the toggleable parent so assistive technology announces the control type.
The label must be part of the same node as the box.
The indeterminate state is announced as partially checked.