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