Skip to content

Commit 83ba040

Browse files
leticiarossiymarian
leticiarossi
authored and
ymarian
committed
[Documentation] Updating Checkbox documentation.
PiperOrigin-RevId: 314146384
1 parent b01058a commit 83ba040

File tree

5 files changed

+208
-33
lines changed

5 files changed

+208
-33
lines changed

‎docs/components/Checkbox.md‎

Lines changed: 208 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,235 @@
11
<!--docs:
2-
title: "Checkboxes"
2+
title: "Material selection controls: CheckBoxes"
33
layout: detail
44
section: components
5-
excerpt: "Checkboxes are independent buttons with two states: selected and unselected."
5+
excerpt: "Selection controls allow the user to select options."
66
iconId: checkbox
77
path: /catalog/checkbox/
88
-->
99

10-
# Checkboxes
10+
# Selection controls: checkboxes
1111

12-
A `CheckBox` represents a button with two states, selected and unselected.
13-
Unlike radio buttons, changes in the states of one checkbox do not usually
14-
affect other checkboxes. A checkbox is a rounded square button with a check to
15-
denote its current state.
12+
[Selection controls](https://material.io/components/selection-controls#usage)
13+
allow the user to select options.
1614

17-
## Design & API Documentation
15+
Use checkboxes to:
1816

19-
- [Material Design guidelines: Checkboxes](https://material.io/go/design-checkboxes)
20-
<!--{: .icon-list-item.icon-list-item--spec }-->
21-
- [Class definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/checkbox/MaterialCheckBox.java)
22-
<!--{: .icon-list-item.icon-list-item--link }-->
23-
- [Class overview](https://developer.android.com/reference/android/widget/CheckBox)
24-
<!--{: .icon-list-item.icon-list-item--link }--> <!--{: .icon-list }-->
17+
* Select one or more options from a list
18+
* Present a list containing sub-selections
19+
* Turn an item on or off in a desktop environment
2520

26-
## Usage
21+
![Checkbox hero example for menu options](assets/checkbox/checkbox_hero.png)
2722

28-
The `MaterialCheckBox` widget provides a complete implementation of Material
29-
Design's checkbox component. It is auto-inflated when using a non-Bridge
30-
Theme.MaterialComponents.\* theme which sets the MaterialComponentsViewInflater.
31-
Example code of how to include the widget in your layout:
23+
## Contents
24+
25+
* [Using checkboxes](#using-checkboxes)
26+
* [Checkbox](#checkbox)
27+
* [Theming checkboxes](#theming-checkboxes)
28+
29+
## Using checkboxes
30+
31+
Before you can use Material checkboxes, you need to add a dependency to the
32+
Material Components for Android library. For more information, go to the
33+
[Getting started](/material-components/material-components-android/blob/master/docs/getting-started.md)
34+
page.
35+
36+
_**Note:** `<CheckBox>` is auto-inflated as
37+
`<com.google.android.material.button.MaterialCheckBox>` via
38+
`MaterialComponentsViewInflater` when using a non-Bridge
39+
`Theme.MaterialComponents.*` theme._
40+
41+
### Making checkboxes accessible
42+
43+
Checkboxes support content labeling for accessibility and are readable by most
44+
screen readers, such as TalkBack. Text rendered in check boxes is automatically
45+
provided to accessibility services. Additional content labels are usually
46+
unnecessary.
47+
48+
## Checkbox
49+
50+
A checkbox is a rounded square button with a check to denote its current state.
51+
Checkboxes allow the user to select one or more items from a set. Checkboxes can
52+
be used to turn an option on or off. Unlike radio buttons, changes in the states
53+
of one checkbox do not usually affect other checkboxes.
54+
55+
### Checkboxes example
56+
57+
API and source code:
58+
59+
* `MaterialCheckBox`
60+
* [Class definition](https://developer.android.com/reference/com/google/android/material/checkbox/MaterialCheckBox)
61+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/checkbox/MaterialCheckBox.java)
62+
63+
The following example shows a list of five checkboxes.
64+
65+
![Example of 5 checkboxes, the first one is checked and the last one is
66+
disabled.](assets/checkbox/checkbox_example.png)
67+
68+
In the layout:
3269

3370
```xml
3471
<CheckBox
35-
android:layout_width="wrap_content"
36-
android:layout_height="wrap_content"/>
72+
android:layout_width="match_parent"
73+
android:layout_height="match_parent"
74+
android:checked="true"
75+
android:text="@string/label_1"/>
76+
<CheckBox
77+
android:layout_width="match_parent"
78+
android:layout_height="match_parent"
79+
android:text="@string/label_2"/>
80+
<CheckBox
81+
android:layout_width="match_parent"
82+
android:layout_height="match_parent"
83+
android:text="@string/label_3"/>
84+
<CheckBox
85+
android:layout_width="match_parent"
86+
android:layout_height="match_parent"
87+
android:text="@string/label_4"/>
88+
<CheckBox
89+
android:layout_width="match_parent"
90+
android:layout_height="match_parent"
91+
android:enabled="false"
92+
android:text="@string/label_5"/>
93+
```
94+
95+
In code:
96+
97+
```kt
98+
// To check a checkbox
99+
checkbox.isChecked = true
100+
101+
// To listen for a checkbox's checked/unchecked state changes
102+
checkbox.setOnCheckedChangeListener { buttonView, isChecked
103+
// Responds to checkbox being checked/unchecked
104+
}
37105
```
38106

39-
### Material Styles
107+
## Key properties
108+
109+
### Checkbox attributes
110+
111+
&nbsp; | Attribute | Related method(s) | Default value
112+
-------------------------- | ------------------------------------------ | ---------------------------------------------------------- | -------------
113+
**To use material colors** | `app:useMaterialThemeColors` | `setUseMaterialThemeColors`<br/>`isUseMaterialThemeColors` | `true` (ignored if `app:buttonTint` is set)
114+
**Color** | `app:buttonTint` | `setButtonTintList`<br/>`getButtonTintList` | `null`
115+
**Min size** | `android:minWidth`<br/>`android:minHeight` | `(set/get)MinWidth`<br/>`(set/get)MinHeight` | `?attr/minTouchTargetSize`
40116

41-
Using a Material Components theme with `MaterialCheckBox` will match the color
42-
of `CheckBox` views to your theme's palette. If you want to override this
43-
behavior, as you might with a custom drawable, set the `useMaterialThemeColors`
44-
parameter to false.
117+
The color of the checbox defaults to `?attr/colorOnSurface` (unchecked) and
118+
`?attr/colorSecondary` (checked) defined in your app theme. If you want to
119+
override this behavior, as you might with a custom drawable that should not be
120+
tinted, set `app:useMaterialThemeColors` to `false`:
45121

46122
```xml
47-
<CheckBox xmlns:android="http://schemas.android.com/apk/res/android"
48-
xmlns:app="http://schemas.android.com/apk/res-auto"
49-
android:layout_width="wrap_content"
50-
android:layout_height="wrap_content"
51-
app:useMaterialThemeColors="false"/>
123+
<CheckBox
124+
...
125+
app:useMaterialThemeColors="false"
126+
/>
52127
```
53128

129+
### Text label attributes
130+
131+
&nbsp; | Attribute | Related method(s) | Default value
132+
-------------- | ------------------------ | ---------------------------------- | -------------
133+
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
134+
**Color** | `android:textColor` | `setTextColor`<br/>`getTextColors` | inherits from `AppCompatRadioButton`
135+
**Typography** | `android:textAppearance` | `setTextAppearance` | inherits from `AppCompatRadioButton`
136+
137+
### Checkbox states
138+
139+
Checkboxes can be selected, unselected, or indeterminate. Checkboxes have
140+
enabled, disabled, hover, focused, and pressed states.
141+
142+
![Checkbox states in an array. Columns are enabled, disabled, hover, focused,
143+
pressed. Rows are selected, unselected, or
144+
indeterminite](assets/checkbox/checkbox_states.png)
145+
54146
### Styles
55147

56-
Use `checkboxStyle` for style changes.
148+
&nbsp; | Style
149+
----------------- | ---------------------------------------------------
150+
**Default style** | `Widget.MaterialComponents.CompoundButton.CheckBox`
151+
152+
Default style theme attribute: `?attr/checkboxStyle`
153+
154+
See the full list of
155+
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/checkbox/res/values/styles.xml)
156+
and
157+
[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/checkbox/res/values/attrs.xml).
158+
159+
## Theming checkboxes
160+
161+
Checkboxes support
162+
[Material Theming](https://material.io/components/selection-controls#theming)
163+
and can be customized in terms of color and typography.
164+
165+
### Checkbox theming example
166+
167+
API and source code:
168+
169+
* `MaterialCheckBox`
170+
* [Class definition](https://developer.android.com/reference/com/google/android/material/checkbox/MaterialCheckBox)
171+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/checkbox/MaterialCheckBox.java)
172+
173+
The following example shows a checkbox with Material Theming.
174+
175+
!["Checkbox theming with pink and brown colors"](assets/checkbox/checkbox_theming.png)
176+
177+
#### Implementing checkbox theming
178+
179+
Using theme attributes in `res/values/styles.xml` (themes all checkboxes and
180+
affects other components):
181+
182+
```xml
183+
<style name="Theme.App" parent="Theme.MaterialComponents.*">
184+
...
185+
<item name="colorOnSurface">@color/shrine_pink_900</item>
186+
<item name="colorSecondary">@color/shrine_pink_100</item>
187+
</style>
188+
189+
```
190+
191+
or using default style theme attributes, styles and theme overlays (themes all
192+
checkboxes but does not affect other components):
57193

58194
```xml
59-
<item name="checkboxStyle">@style/Widget.MaterialComponents.CompoundButton.CheckBox</item>
195+
<style name="Theme.App" parent="Theme.MaterialComponents.*">
196+
...
197+
<item name="checkboxStyle">@style/Widget.App.CheckBox</item>
198+
</style>
199+
200+
<style name="Widget.App.CheckBox" parent="Widget.MaterialComponents.CompoundButton.CheckBox">
201+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.CheckBox</item>
202+
</style>
203+
204+
<style name="ThemeOverlay.App.CheckBox" parent="">
205+
<item name="colorOnSurface">@color/shrine_pink_900</item>
206+
<item name="colorSecondary">@color/shrine_pink_100</item>
207+
</style>
208+
```
209+
210+
you can also change the checkbox colors via the `?attr/buttonTint` attribute:
211+
212+
```xml
213+
<style name="Widget.App.CheckBox" parent="Widget.MaterialComponents.CompoundButton.CheckBox">
214+
<item name="buttonTint">@color/button_tint</item>
215+
</style>
216+
```
217+
218+
and in `color/button_tint.xml`:
219+
220+
```xml
221+
<selector xmlns:android="http://schemas.android.com/apk/res/android">
222+
<item android:color=">@color/shrine_pink_900" android:state_checked="true"/>
223+
<item android:alpha="0.38" android:color="@color/shrine_pink_100" android:state_enabled="false"/>
224+
<item android:color="@color/shrine_pink_100"/>
225+
</selector>
226+
```
227+
228+
or using the styles in the layout (affects only this checkbox):
229+
230+
```xml
231+
<CheckBox
232+
...
233+
style="@style/Widget.App.CheckBox"
234+
/>
60235
```

‎docs/components/assets/checkbox/checkbox_example.png‎

16.2 KB
Loading

‎docs/components/assets/checkbox/checkbox_hero.png‎

23.6 KB
Loading

‎docs/components/assets/checkbox/checkbox_states.png‎

73.7 KB
Loading

‎docs/components/assets/checkbox/checkbox_theming.png‎

16 KB
Loading

0 commit comments

Comments
 (0)