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
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.
Note: <CheckBox>
is auto-inflated as
<com.google.android.material.button.MaterialCheckBox>
via
MaterialComponentsViewInflater
when using a Theme.Material3.*
theme.
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.
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.
API and source code:
MaterialCheckBox
The following example shows a list of five checkboxes.
In the layout:
<CheckBox
android:layout_width="match_parent"
android:layout_height="match_parent"
android:checked="true"
android:text="@string/label_1"/>
<CheckBox
android:layout_width="match_parent"
android:layout_height="match_parent"
android:text="@string/label_2"/>
<CheckBox
android:layout_width="match_parent"
android:layout_height="match_parent"
android:text="@string/label_3"/>
<CheckBox
android:layout_width="match_parent"
android:layout_height="match_parent"
android:text="@string/label_4"/>
<CheckBox
android:layout_width="match_parent"
android:layout_height="match_parent"
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
}
Element | Attribute | Related method(s) | Default value |
---|---|---|---|
To use material colors | app:useMaterialThemeColors |
setUseMaterialThemeColors isUseMaterialThemeColors |
true (ignored if app:buttonTint is set) |
Color | app:buttonTint |
setButtonTintList getButtonTintList |
?attr/colorOnSurface (see all states) |
Min size | android:minWidth android:minHeight |
(set/get)MinWidth (set/get)MinHeight |
?attr/minTouchTargetSize |
The color of the checkbox defaults to ?attr/colorOnSurface
(unchecked) and
?attr/colorPrimary
(checked) defined in your app theme. If you want to
override this behavior, as you might with a custom drawable that should not be
tinted, set app:useMaterialThemeColors
to false
:
<CheckBox
...
app:useMaterialThemeColors="false"
/>
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 |
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.
Element | Style |
---|---|
Default style | Widget.Material3.CompoundButton.CheckBox |
Default style theme attribute: ?attr/checkboxStyle
See the full list of styles and attrs.
Checkboxes support Material Theming which can customize color and typography.
API and source code:
MaterialCheckBox
The following example shows a checkbox with Material 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"
/>