1 |
|
2 | title: "Checkboxes"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "Checkboxes allow the user to select multiple options from a set."
|
6 | iconId: selection_control
|
7 | path: /catalog/input-controls/checkboxes/
|
8 | -->
|
9 |
|
10 | # Selection controls: checkboxes
|
11 |
|
12 | [Selection controls](https://material.io/components/selection-controls#usage) allow the user to select options.
|
13 |
|
14 | Use checkboxes to:
|
15 |
|
16 | * Select one or more options from a list
|
17 | * Present a list containing sub-selections
|
18 | * Turn an item on or off in a desktop environment
|
19 |
|
20 | ![Checkbox hero example for menu options](images/checkbox-hero.png)
|
21 |
|
22 | **Contents**
|
23 |
|
24 | * [Using checkboxes](#using-checkboxes)
|
25 | * [Checkboxes](#checkboxes)
|
26 | * [Other variants](#other-variants)
|
27 | * [API](#api)
|
28 | * [Usage within web frameworks](#usage-within-web-frameworks)
|
29 |
|
30 | ## Using checkboxes
|
31 |
|
32 | Checkboxes allow the user to select one or more items from a set. Checkboxes can be used to turn an option on or off.
|
33 |
|
34 | ### Installing checkboxes
|
35 |
|
36 | ```
|
37 | npm install @material/checkbox
|
38 | ```
|
39 |
|
40 | ### Styles
|
41 |
|
42 | ```scss
|
43 | @use "@material/checkbox";
|
44 | @use "@material/form-field";
|
45 |
|
46 | @include checkbox.core-styles;
|
47 | @include form-field.core-styles;
|
48 | ```
|
49 |
|
50 | **Note: The form field styles are only required when the checkbox is used with the form field.**
|
51 |
|
52 | ### JavaScript instantiation
|
53 |
|
54 | The checkbox will work without JavaScript, but you can enhance it with a ripple interaction effect by instantiating `MDCCheckbox` on the `mdc-checkbox` element. To activate the ripple effect upon interacting with the label, you must also instantiate `MDCFormField` on the `mdc-form-field` element and set the `MDCCheckbox` instance as its `input`.
|
55 |
|
56 | ```js
|
57 | import {MDCFormField} from '@material/form-field';
|
58 | import {MDCCheckbox} from '@material/checkbox';
|
59 |
|
60 | const checkbox = new MDCCheckbox(document.querySelector('.mdc-checkbox'));
|
61 | const formField = new MDCFormField(document.querySelector('.mdc-form-field'));
|
62 | formField.input = checkbox;
|
63 | ```
|
64 |
|
65 | > See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
|
66 |
|
67 | ### Making checkboxes accessible
|
68 |
|
69 | Material Design spec advises that touch targets should be at least 48px x 48px.
|
70 | To meet this requirement, add the `mdc-checkbox--touch` class to your checkbox as follows:
|
71 |
|
72 | ```html
|
73 | <div class="mdc-touch-target-wrapper">
|
74 | <div class="mdc-checkbox mdc-checkbox--touch">
|
75 | <input type="checkbox"
|
76 | class="mdc-checkbox__native-control"
|
77 | id="checkbox-1"/>
|
78 | <div class="mdc-checkbox__background">
|
79 | <svg class="mdc-checkbox__checkmark"
|
80 | viewBox="0 0 24 24">
|
81 | <path class="mdc-checkbox__checkmark-path"
|
82 | fill="none"
|
83 | d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
|
84 | </svg>
|
85 | <div class="mdc-checkbox__mixedmark"></div>
|
86 | </div>
|
87 | <div class="mdc-checkbox__ripple"></div>
|
88 | <div class="mdc-checkbox__focus-ring"></div>
|
89 | </div>
|
90 | </div>
|
91 | ```
|
92 |
|
93 | Note that the outer `mdc-touch-target-wrapper` element is only necessary if you want to avoid potentially overlapping touch targets on adjacent elements (due to collapsing margins).
|
94 |
|
95 | The `mdc-checkbox__focus-ring` element ensures that a focus indicator is displayed in high contrast mode around the active/focused checkbox.
|
96 |
|
97 | ## Checkboxes
|
98 |
|
99 | We recommend using MDC Checkbox with [MDC Form Field](../mdc-form-field) for enhancements such as label alignment, label activation of the ripple interaction effect, and RTL-awareness.
|
100 |
|
101 | ### Checkbox example
|
102 |
|
103 | ```html
|
104 | <div class="mdc-form-field">
|
105 | <div class="mdc-checkbox">
|
106 | <input type="checkbox"
|
107 | class="mdc-checkbox__native-control"
|
108 | id="checkbox-1"/>
|
109 | <div class="mdc-checkbox__background">
|
110 | <svg class="mdc-checkbox__checkmark"
|
111 | viewBox="0 0 24 24">
|
112 | <path class="mdc-checkbox__checkmark-path"
|
113 | fill="none"
|
114 | d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
|
115 | </svg>
|
116 | <div class="mdc-checkbox__mixedmark"></div>
|
117 | </div>
|
118 | <div class="mdc-checkbox__ripple"></div>
|
119 | <div class="mdc-checkbox__focus-ring"></div>
|
120 | </div>
|
121 | <label for="checkbox-1">Checkbox 1</label>
|
122 | </div>
|
123 | ```
|
124 |
|
125 | **Note: If you are using IE, you need to include a closing `</path>` tag if you wish to avoid console warnings.**
|
126 |
|
127 | ### Checkbox states
|
128 |
|
129 | Checkboxes can be selected, unselected, or indeterminate. Checkboxes have enabled, disabled, hover, focused, and pressed states.
|
130 |
|
131 | ![Checkbox states in a table. Columns are enabled, disabled, hover, focused, pressed. Rows are selected, unselected, or indeterminite](images/checkbox-states.png)
|
132 |
|
133 | ## Other variants
|
134 |
|
135 | ### Disabled checkboxes
|
136 |
|
137 | Note that `mdc-checkbox--disabled` is necessary on the root element of CSS-only checkboxes to prevent hover states from activating. Checkboxes that use the JavaScript component do not need this class; a `disabled` attribute on the `<input>` element is sufficient.
|
138 |
|
139 | ```html
|
140 | <div class="mdc-checkbox mdc-checkbox--disabled">
|
141 | <input type="checkbox"
|
142 | id="basic-disabled-checkbox"
|
143 | class="mdc-checkbox__native-control"
|
144 | disabled />
|
145 | <div class="mdc-checkbox__background">
|
146 | <svg class="mdc-checkbox__checkmark"
|
147 | viewBox="0 0 24 24">
|
148 | <path class="mdc-checkbox__checkmark-path"
|
149 | fill="none"
|
150 | d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
|
151 | </svg>
|
152 | <div class="mdc-checkbox__mixedmark"></div>
|
153 | </div>
|
154 | <div class="mdc-checkbox__ripple"></div>
|
155 | <div class="mdc-checkbox__focus-ring"></div>
|
156 | </div>
|
157 | <label for="basic-disabled-checkbox" id="basic-disabled-checkbox-label">This is my disabled checkbox</label>
|
158 | ```
|
159 |
|
160 | ### Indeterminate checkboxes
|
161 |
|
162 | Note that `data-indeterminate="true"` is necessary on the input element for initial render, or in a CSS-only mode. Checkboxes that use the Javascript component can modify the `indeterminate` property at runtime.
|
163 |
|
164 | ```html
|
165 | <div class="mdc-checkbox">
|
166 | <input type="checkbox"
|
167 | id="basic-indeterminate-checkbox"
|
168 | class="mdc-checkbox__native-control"
|
169 | data-indeterminate="true"/>
|
170 | <div class="mdc-checkbox__background">
|
171 | <svg class="mdc-checkbox__checkmark"
|
172 | viewBox="0 0 24 24">
|
173 | <path class="mdc-checkbox__checkmark-path"
|
174 | fill="none"
|
175 | d="M1.73,12.91 8.1,19.28 22.79,4.59"/>
|
176 | </svg>
|
177 | <div class="mdc-checkbox__mixedmark"></div>
|
178 | </div>
|
179 | <div class="mdc-checkbox__ripple"></div>
|
180 | <div class="mdc-checkbox__focus-ring"></div>
|
181 | </div>
|
182 | <label for="basic-indeterminate-checkbox" id="basic-indeterminate-checkbox-label">This is my indeterminate checkbox</label>
|
183 | ```
|
184 |
|
185 | ## API
|
186 |
|
187 | ### Sass mixins
|
188 |
|
189 | MDC Checkbox uses [MDC Theme](../mdc-theme)'s `secondary` color by default for "marked" states (i.e., checked or indeterminate).
|
190 |
|
191 | Mixin | Description
|
192 | --- | ---
|
193 | `container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-stroke-color, $marked-fill-color, $generate-keyframes)` | Sets stroke & fill colors for both marked and unmarked state of enabled checkbox. Set $generate-keyframes to false to prevent the mixin from generating @keyframes.
|
194 | `disabled-container-colors($unmarked-stroke-color, $unmarked-fill-color, $marked-stroke-color, $marked-fill-color)` | Sets stroke & fill colors for both marked and unmarked state of disabled checkbox.
|
195 | `ink-color($color)` | Sets the ink color of the checked and indeterminate icons for an enabled checkbox
|
196 | `disabled-ink-color($color)` | Sets the ink color of the checked and indeterminate icons for a disabled checkbox
|
197 | `focus-indicator-color($color)` | Sets the color of the focus indicator (ripple) when checkbox is selected or is in indeterminate state.
|
198 | `ripple-size($ripple-size)` | Sets the ripple size of the checkbox.
|
199 | `density($density-scale)` | Sets density scale for checkbox, Supported density scales are `-3`, `-2`, `-1`, and `0` (default).
|
200 |
|
201 | The ripple effect for the Checkbox component is styled using [MDC Ripple](../mdc-ripple) mixins.
|
202 |
|
203 | ### `MDCCheckbox` properties and methods
|
204 |
|
205 | Property Name | Type | Description
|
206 | --- | --- | ---
|
207 | `checked` | `boolean` | Setter/getter for the checkbox's checked state
|
208 | `indeterminate` | `boolean` | Setter/getter for the checkbox's indeterminate state
|
209 | `disabled` | `boolean` | Setter/getter for the checkbox's disabled state
|
210 | `value` | `string` | Setter/getter for the checkbox's
|
211 |
|
212 | ## Usage within web frameworks
|
213 |
|
214 | If you are using a JavaScript framework, such as React or Angular, you can create a Checkbox for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).
|
215 |
|
216 | ### `MDCCheckboxAdapter`
|
217 |
|
218 | Method Signature | Description
|
219 | --- | ---
|
220 | `addClass(className: string) => void` | Adds a class to the root element.
|
221 | `removeClass(className: string) => void` | Removes a class from the root element.
|
222 | `forceLayout() => void` | Force-trigger a layout on the root element. This is needed to restart animations correctly. If you find that you do not need to do this, you can simply make it a no-op.
|
223 | `isAttachedToDOM() => boolean` | Returns true if the component is currently attached to the DOM, false otherwise.
|
224 | `isIndeterminate() => boolean` | Returns true if the component is in the indeterminate state.
|
225 | `isChecked() => boolean` | Returns true if the component is checked.
|
226 | `hasNativeControl() => boolean` | Returns true if the input is present in the component.
|
227 | `setNativeControlDisabled(disabled: boolean) => void` | Sets the input to disabled.
|
228 | `setNativeControlAttr(attr: string, value: string) => void` | Sets an HTML attribute to the given value on the native input element.
|
229 | `removeNativeControlAttr(attr: string) => void` | Removes an attribute from the native input element.
|
230 |
|
231 | ### `MDCCheckboxFoundation`
|
232 |
|
233 | Method Signature | Description
|
234 | --- | ---
|
235 | `setDisabled(disabled: boolean) => void` | Updates the `disabled` property on the underlying input. Does nothing when the underlying input is not present.
|
236 | `handleAnimationEnd() => void` | `animationend` event handler that should be applied to the root element.
|
237 | `handleChange() => void` | `change` event handler that should be applied to the checkbox element.
|