Checkbox

Checkboxes let users select one or more items from a list. You might use a checkbox to let the user do the following:

Turn an item on or off.
Select from multiple options in a list.
Indicate agreement or acceptance.

Anatomy

A checkbox consists of the following elements:

Box: This is the container for the checkbox.
Check: This is the visual indicator that shows whether the checkbox is selected or not.
Label: This is the text that describes the checkbox.

States

A checkbox can be in one of three states:

Unselected: The checkbox is not selected. The box is empty.
Indeterminate: The checkbox is in an indeterminate state. The box contains a dash.
Selected: The checkbox is selected. The box contains a checkmark.

The following image demonstrates the three states of a checkbox.

An example of a checkbox component in each of its three states: unselected, selected, and indeterminate. — **Figure 1.** The three states of a checkbox. Unselected, indeterminate, and selected.

Implementation

You can use the Checkbox composable to create a checkbox in your app. There are just a few key parameters to keep in mind:

checked: The boolean that captures whether the checkbox is checked or unchecked.
onCheckedChange(): The function that the app calls when the user taps the checkbox.

The following snippet demonstrates how to use the Checkbox composable:

@Composable
fun CheckboxMinimalExample() {
    var checked by remember { mutableStateOf(true) }

    Row(
        verticalAlignment = Alignment.CenterVertically,
    ) {
        Text(
            "Minimal checkbox"
        )
        Checkbox(
            checked = checked,
            onCheckedChange = { checked = it }
        )
    }

    Text(
        if (checked) "Checkbox is checked" else "Checkbox is unchecked"
    )
}Checkbox.kt

Explanation

This code creates a checkbox that is initially unchecked. When the user clicks on the checkbox, the onCheckedChange lambda updates the checked state.

Result

This example produces the following component when unchecked:

An unchecked checkbox with a label. The text beneath it reads 'Checkbox is unchecked' — **Figure 2.** Unchecked checkbox

And this is how the same checkbox appears when checked:

A checked checkbox with a label. The text beneath it reads 'Checkbox is checked' — **Figure 3.** Checked checkbox

Advanced example

The following is a more complex example of how you can implement checkboxes in your app. In this snippet, there is a parent checkbox and a series of child checkboxes. When the user taps the parent checkbox, the app checks all child checkboxes.

@Composable
fun CheckboxParentExample() {
    // Initialize states for the child checkboxes
    val childCheckedStates = remember { mutableStateListOf(false, false, false) }

    // Compute the parent state based on children's states
    val parentState = when {
        childCheckedStates.all { it } -> ToggleableState.On
        childCheckedStates.none { it } -> ToggleableState.Off
        else -> ToggleableState.Indeterminate
    }

    Column {
        // Parent TriStateCheckbox
        Row(
            verticalAlignment = Alignment.CenterVertically,
        ) {
            Text("Select all")
            TriStateCheckbox(
                state = parentState,
                onClick = {
                    // Determine new state based on current state
                    val newState = parentState != ToggleableState.On
                    childCheckedStates.forEachIndexed { index, _ ->
                        childCheckedStates[index] = newState
                    }
                }
            )
        }

        // Child Checkboxes
        childCheckedStates.forEachIndexed { index, checked ->
            Row(
                verticalAlignment = Alignment.CenterVertically,
            ) {
                Text("Option ${index + 1}")
                Checkbox(
                    checked = checked,
                    onCheckedChange = { isChecked ->
                        // Update the individual child state
                        childCheckedStates[index] = isChecked
                    }
                )
            }
        }
    }

    if (childCheckedStates.all { it }) {
        Text("All options selected")
    }
}Checkbox.kt

Explanation

The following are several points you should note from this example:

State management:
- childCheckedStates: A list of booleans using mutableStateOf() to track the checked state of each child checkbox.
- parentState: A ToggleableState whose value derives from the child checkboxes' states.
UI components:
- TriStateCheckbox: Is necessary for the parent checkbox as it has a state param that lets you set it to indeterminate.
- Checkbox: Used for each child checkbox with its state linked to the corresponding element in childCheckedStates.
- Text: Displays labels and messages ("Select all", "Option X", "All options selected").
Logic:
- The parent checkbox's onClick updates all child checkboxes to the opposite of the current parent state.
- Each child checkbox's onCheckedChange updates its corresponding state in the childCheckedStates list.
- The code displays "All options selected" when all child checkboxes are checked.

Result

This example produces the following component when all checkboxes are unchecked.

A series of unchecked labeled checkboxes with a label. — **Figure 4.** Unchecked checkboxes

Likewise, this is how the component appears when all options are checked, as when the user taps select all:

A series of checked labeled checkboxes checkbox with a label. The first is marked 'select all'. There is a text component beneath them that reads 'all options selected.' — **Figure 5.** Checked checkboxes

When only one option is checked the parent checkbox display the indeterminate state:

A series of unchecked labeled checkboxes checkbox with a label. All but one is unchecked. The checkbox labeled 'select all' is indeterminate, displaying a dash. — **Figure 6.** Indeterminate checkbox

Additional resources

Material Design Checkboxes