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.
<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.
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.
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."
In the layout:
<CheckBox
...
app:checkedState="indeterminate"/>
In code:
// You can set the state of the checkbox (STATE_CHECKED, STATE_UNCHECKED,
// or STATE_INDETERMINATE) via setCheckedState.
checkBox.setCheckedState(MaterialCheckbox.STATE_INDETERMINATE);
// Checkbox state listener.
checkbox.addOnCheckedStateChangedListener { checkBox, state ->
// Responds to when the checkbox changes state.
}
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="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
}
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.
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.
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"
/>