Material 3 Checkboxes

Overview

Checkboxes allow users to select multiple options or toggle settings.

Material 3 Checkboxes, using MaterialCheckBox, support checked, unchecked, indeterminate, and error states, with built-in accessibility for screen readers. They are ideal for lists or hierarchical selections (e.g., parent-child checkboxes). This guide covers implementation, accessibility, and theming, noting that shape theming is not supported.

Getting Started

• Add Material Components for Android library dependency
• Use MaterialCheckBox with Theme.Material3.*
• Support checked, unchecked, indeterminate, and error states

Accessibility

• Labels auto-provided for TalkBack; add android:contentDescription for custom labels
• Use errorAccessibilityLabel for custom error announcements
• Ensure sufficient contrast for visibility

Behavior and States

• States: Checked, Unchecked, Indeterminate, Error (with enabled, disabled, hover, focused, pressed)
• Toggle with isChecked or checkedState
• Set error with errorShown
• Listen for changes with OnCheckedStateChangedListener or OnErrorChangedListener

      
val checkbox = findViewById<MaterialCheckBox>(R.id.checkbox)
checkbox.checkedState = MaterialCheckBox.STATE_CHECKED
checkbox.errorShown = true
checkbox.errorAccessibilityLabel = "Error: custom error announcement"
checkbox.addOnCheckedStateChangedListener { _, state ->
    // Handle state change
}
checkbox.addOnErrorChangedListener { _, errorShown ->
    // Handle error state change
}
      
    

Checkbox Anatomy

Component	Description	Checked State	Unchecked State	Indeterminate State	Error State
Container	Rounded square, holds icon	colorPrimary background	colorOnSurface outline	colorPrimary background	colorError outline
Icon	Checkmark or dash	colorOnPrimary checkmark	Hidden	colorOnPrimary dash	colorOnError if shown
Label	Optional text description	Visible if set	Visible if set	Visible if set	Visible if set

Checkbox Example

• Supports hierarchical parent-child relationships
• Handles checked, unchecked, indeterminate, and error states

Example

      
<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">
    <com.google.android.material.checkbox.MaterialCheckBox
        android:id="@+id/checkbox_parent"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:checkedState="indeterminate"
        android:text="@string/label_parent"
        android:contentDescription="@string/parent_desc"/>
    <LinearLayout
        android:id="@+id/checkbox_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginStart="16dp"
        android:orientation="vertical">
        <com.google.android.material.checkbox.MaterialCheckBox
            android:id="@+id/checkbox_child_1"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/label_child_1"
            android:contentDescription="@string/child_1_desc"/>
        <com.google.android.material.checkbox.MaterialCheckBox
            android:id="@+id/checkbox_child_2"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/label_child_2"
            android:contentDescription="@string/child_2_desc"/>
        <com.google.android.material.checkbox.MaterialCheckBox
            android:id="@+id/checkbox_child_3"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/label_child_3"
            android:contentDescription="@string/child_3_desc"/>
        <com.google.android.material.checkbox.MaterialCheckBox
            android:id="@+id/checkbox_child_4"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:text="@string/label_child_4"
            android:contentDescription="@string/child_4_desc"/>
    </LinearLayout>
</LinearLayout>
      
    

      
private var isUpdatingChildren = false
val parent = findViewById<MaterialCheckBox>(R.id.checkbox_parent)
val children = listOf(
    findViewById<MaterialCheckBox>(R.id.checkbox_child_1),
    findViewById<MaterialCheckBox>(R.id.checkbox_child_2),
    findViewById<MaterialCheckBox>(R.id.checkbox_child_3),
    findViewById<MaterialCheckBox>(R.id.checkbox_child_4)
)
val parentListener = MaterialCheckBox.OnCheckedStateChangedListener { _, state ->
    if (state != MaterialCheckBox.STATE_INDETERMINATE) {
        isUpdatingChildren = true
        children.forEach { it.isChecked = parent.isChecked }
        isUpdatingChildren = false
    }
}
parent.addOnCheckedStateChangedListener(parentListener)
val childListener = MaterialCheckBox.OnCheckedStateChangedListener { _, _ ->
    if (!isUpdatingChildren) {
        val checkedCount = children.count { it.isChecked }
        parent.removeOnCheckedStateChangedListener(parentListener)
        parent.checkedState = when {
            checkedCount == children.size -> MaterialCheckBox.STATE_CHECKED
            checkedCount == 0 -> MaterialCheckBox.STATE_UNCHECKED
            else -> MaterialCheckBox.STATE_INDETERMINATE
        }
        parent.addOnCheckedStateChangedListener(parentListener)
    }
}
children.forEach { it.addOnCheckedStateChangedListener(childListener) }
children[0].isChecked = true
      
    

Attributes and Usage

Element	Attribute	Related Method(s)	Default Value	Usage Description
Container	app:buttonTint	setButtonTintList, getButtonTintList	?attr/colorOnSurface	Sets container color (states)
Container	app:buttonIcon	setButtonIconDrawable, getButtonIconDrawable	@mtrl_checkbox_button_icon	Sets icon drawable
Icon	app:buttonIconTint	setButtonIconTintList, getButtonIconTintList	?attr/colorOnPrimary	Sets icon color (states)
Container	app:centerIfNoTextEnabled	setCenterIfNoTextEnabled, isCenterIfNoTextEnabled	true	Centers icon if no label
Label	android:text	setText, getText	null	Sets label text
Label	android:textColor	setTextColor, getTextColors	Inherits from AppCompatCheckBox	Sets label color
State	app:checkedState	setCheckedState, getCheckedState	unchecked	Sets state (checked, unchecked, indeterminate)
State	app:errorShown	setErrorShown, isErrorShown	false	Sets error state

Theming Checkboxes

• Customize color and typography
• Shape theming not supported (rounded square only)

Example

      
<style name="Theme.App" parent="Theme.Material3.*">
    <item name="colorPrimary">@color/shrine_primary</item>
    <item name="colorSurface">@color/shrine_surface</item>
</style>
      
    

      
<style name="Theme.App" parent="Theme.Material3.*">
    <item name="checkboxStyle">@style/Widget.App.CheckBox</item>
</style>
<style name="Widget.App.CheckBox" parent="Widget.Material3.CompoundButton.CheckBox">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.CheckBox</item>
</style>
<style name="ThemeOverlay.App.CheckBox" parent="">
    <item name="colorPrimary">@color/shrine_primary</item>
    <item name="colorSurface">@color/shrine_surface</item>
    <item name="colorError">@color/shrine_error</item>
    <item name="colorOnPrimary">@color/shrine_on_primary</item>
</style>
      
    

      
<!-- res/color/button_tint.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:alpha="0.38" android:color="@color/shrine_on_surface" android:state_enabled="false"/>
    <item android:color="@color/shrine_error" app:state_error="true"/>
    <item android:color="@color/shrine_primary" app:state_indeterminate="true"/>
    <item android:color="@color/shrine_primary" android:state_checked="true"/>
</selector>
<!-- res/color/button_icon_tint.xml -->
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:color="@color/shrine_surface" android:state_enabled="false"/>
    <item android:color="@color/shrine_on_error" app:state_error="true"/>
    <item android:color="@color/shrine_on_primary" app:state_indeterminate="true"/>
    <item android:color="@color/shrine_on_primary" android:state_checked="true"/>
</selector>
      
    

Material Design Documentation

• Adheres to Material Design guidelines for Checkboxes
• Covers design, behavior, theming specifications
• Includes accessibility and state management
• Refer to Material Design documentation for full details

FAQ

What are Material 3 Checkboxes?

• Controls for selecting multiple options or toggling settings

---

What states do they support?

• Checked, unchecked, indeterminate, error

---

When to use indeterminate state?

• Use for parent checkboxes with partial child selections

---

How to make them accessible?

• Labels auto-provided; add custom contentDescription

---

Can I customize appearance?

• Yes, theme colors and typography, no shape theming

---

How to add the Material 3 library?

• Include Material Components for Android library

---

Are there updates for the latest standards?

• Reflects latest Material 3 standards for Checkboxes