material-components_material-components-android/docs/components/Checkbox.md

Selection controls: checkboxes

Selection controls allow the user to select options.

Use checkboxes to:

• Select one or more options from a list
• Present a list containing sub-selections
• Turn an item on or off in a desktop environment

Contents

• Using checkboxes
• Checkbox
• Theming checkboxes

Using checkboxes

Before you can use Material checkboxes, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/label"/>

Note: <CheckBox> is auto-inflated as <com.google.android.material.button.MaterialCheckBox> via MaterialComponentsViewInflater when using a Theme.Material3.* theme.

Making checkboxes accessible

Checkboxes support content labeling for accessibility and are readable by most screen readers, such as TalkBack. Text rendered in check boxes is automatically provided to accessibility services. Additional content labels are usually unnecessary.

Setting the error state on checkbox

In the layout:

<CheckBox
    ...
    app:errorShown="true"/>

In code:

// Set error.
checkbox.errorShown = true

// Optional listener:
checkbox.addOnErrorChangedListener { checkBox, errorShown ->
    // Responds to when the checkbox enters/leaves error state
  }
}

// To set a custom accessibility label:
checkbox.errorAccessibilityLabel = "Error: custom error announcement."

Checkbox

A checkbox is a square button with a check to denote its current state. Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off. Unlike radio buttons, changes in the states of one checkbox do not usually affect other checkboxes.

Note: Checkboxes do not support shape theming and are only rounded square checkboxes.

Checkboxes example

API and source code:

• MaterialCheckBox
  • Class definition
  • Class source

The following example shows a list of five checkboxes.

In the layout:

<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:checked="true"
    android:text="@string/label_1"/>
<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/label_2"/>
<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/label_3"/>
<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/label_4"/>
<CheckBox
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:enabled="false"
    android:text="@string/label_5"/>

In code:

// To check a checkbox
checkbox.isChecked = true

// To listen for a checkbox's checked/unchecked state changes
checkbox.setOnCheckedChangeListener { buttonView, isChecked ->
    // Responds to checkbox being checked/unchecked
}

Key properties

Checkbox attributes

The checkbox is composed of an app:buttonCompat button drawable (the squared icon) and an app:buttonIcon icon drawable (the checkmark icon) layered on top of it.

Element	Attribute	Related method(s)	Default value
To use material colors	app:useMaterialThemeColors	setUseMaterialThemeColors isUseMaterialThemeColors	true (ignored if app:buttonTint is set)
Button drawable	app:buttonCompat	setButtonDrawable getButtonDrawable	@mtrl_checkbox_button
Button tint	app:buttonTint	setButtonTintList getButtonTintList	?attr/colorOnSurface (see all states)
Button icon drawable	app:buttonIcon	setButtonIconDrawable getButtonIconDrawable	@mtrl_checkbox_button_icon
Button icon tint	app:buttonIconTint	setButtonIconTintList getButtonIconTintList	?attr/colorOnPrimary (see all states)
Min size	android:minWidth android:minHeight	(set/get)MinWidth (set/get)MinHeight	?attr/minTouchTargetSize
Centered icon if no text	app:centerIfNoTextEnabled	setCenterIfNoTextEnabled isCenterIfNoTextEnabled	true

Note: If you'd like to change the default colors, override the above tint attributes or set them to @null and app:useMaterialThemeColors to false.

<CheckBox
        ...
    app:useMaterialThemeColors="false"
    />

Note: If setting a custom app:buttonCompat, make sure to also set app:buttonIcon if an icon is desired. The checkbox does not support having a custom app:buttonCompat and preserving the default app:buttonIcon checkmark at the same time.

Text label attributes

Element	Attribute	Related method(s)	Default value
Text label	android:text	setText getText	null
Color	android:textColor	setTextColor getTextColors	inherits from AppCompatCheckBox
Typography	android:textAppearance	setTextAppearance	?attr/textAppearanceBodyMedium

Checkbox states

Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused, and pressed states.

Note: MaterialCheckBox does not support the indeterminate state. Only selected and unselected states are supported.

Styles

Element	Style
Default style	Widget.Material3.CompoundButton.CheckBox

Default style theme attribute: ?attr/checkboxStyle

See the full list of styles and attrs.

Theming checkboxes

Checkboxes support Material Theming which can customize color and typography.

Checkbox theming example

API and source code:

• MaterialCheckBox
  • Class definition
  • Class source

The following example shows a checkbox with Material Theming.

Implementing checkbox theming

Use theme attributes in res/values/styles.xml, which adds a theme to all checkboxes and affects other components:

<style name="Theme.App" parent="Theme.Material3.*">
    ...
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="colorSecondary">@color/shrine_pink_100</item>
</style>

Use default style theme attributes, styles and theme overlays, which will add a theme to all checkboxes but does not affect other components:

<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="colorOnSurface">@color/shrine_pink_900</item>
    <item name="colorSecondary">@color/shrine_pink_100</item>
</style>

You can also change the checkbox colors via the ?attr/buttonTint attribute:

<style name="Widget.App.CheckBox" parent="Widget.Material3.CompoundButton.CheckBox">
   <item name="buttonTint">@color/button_tint</item>
</style>

and in color/button_tint.xml:

<selector xmlns:android="http://schemas.android.com/apk/res/android">
  <item android:color="@color/shrine_pink_900" android:state_checked="true"/>
  <item android:alpha="0.38" android:color="@color/shrine_pink_100" android:state_enabled="false"/>
  <item android:color="@color/shrine_pink_100"/>
</selector>

Use the styles in the layout. That affects only this checkbox:

<CheckBox
        ...
    style="@style/Widget.App.CheckBox"
    />