You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use Checkbox Groups when you have multiple binary choices to make but all choices belong to a single group or field. Example: Choosing capabilities when searching for a phone number to provision from Twilio. By placing them in a group, users should be able to clearly understand which options make up the collection and how those options are related to each other.
60
60
61
-
Checkbox groups are used when you have multiple binary choices to make but all choices belong to a single group or field. For example, choosing capabilities when searching for a Phone Number to provision from Twilio. By placing them in a group, users should be able to clearly understand which options make up the collection and also how those options are related to each other.
61
+
For guidance on using a Checkbox in a form, refer to our [Form pattern](/patterns/form) guidelines.
62
+
63
+
### About Checkbox
64
+
65
+
Use a checkbox to present a user with a binary (e.g. on/off) choice that is part of a form. A checkbox should not be used to apply a user's choice instantly. In that case, such as enabling a system feature, use the [Switch component](/components/switch).
62
66
63
67
#### Accessibility
64
68
65
-
- Checkbox groups **must** have a group legend that describes the collection.
66
-
- The label _should_ be visible.
67
-
- The label may be visually hidden or provided via `aria-label`on the group component if the entire form is just a single checkbox group with no other form elements. The grouping should be visually implicit, but a description still needs to be provided for assistive technology.
69
+
- Checkbox Group must have a group legend that describes the collection. The label should be visible. However if the entire form is just a single checkbox group with no other form elements, it may be visually hidden or provided via `aria-label` on the group component. The grouping should be visually implicit, but a description still needs to be provided for assistive technology.
70
+
- Checkbox must have a visible label.
71
+
- When displaying additional content based on checking a checkbox, be sure that the new content appears after the checkbox so that it is naturally discoverable by assistive technology users.
68
72
69
73
### Checkbox
70
74
@@ -81,23 +85,23 @@ Use a checkbox to present a user with a binary (e.g. on/off) choice that is part
81
85
82
86
## Controlled vs. uncontrolled checkboxes
83
87
84
-
The checkbox can either be controlled, meaning there is an external state that determines if the checkbox is checked or not, or uncontrolled, meaning the checkbox manages its own state.
88
+
Checkbox can either be controlled, meaning there is an external state that determines if the checkbox is checked or not, or uncontrolled, meaning the checkbox manages its own state.
85
89
86
-
To make an uncontrolled checkbox, you do not pass the `checked` or `onChange` props. If you need the checkbox to be checked by default, use the `defaultChecked` prop.
90
+
To make an uncontrolled checkbox, do not pass the `checked` or `onChange` props. If you need the checkbox to be checked by default, use the `defaultChecked` prop.
87
91
88
92
<LivePreviewscope={{Checkbox}}noInline>
89
93
{uncontrolledCheckbox}
90
94
</LivePreview>
91
95
92
-
To make a controlled checkbox, you must pass the `checked` and `onChange` props. You cannot use the `defaultChecked` prop in a controlled checkbox.
96
+
To make a controlled checkbox, pass the `checked` and `onChange` props. You cannot use the `defaultChecked` prop in a controlled checkbox.
93
97
94
98
<LivePreviewscope={{Checkbox}}noInline>
95
99
{controlledCheckbox}
96
100
</LivePreview>
97
101
98
-
## Examples
102
+
## Checkbox examples
99
103
100
-
### Basic checkbox with label
104
+
### Basic Checkbox with Label
101
105
102
106
A checkbox is always displayed next to a visible label.
103
107
@@ -107,8 +111,7 @@ A checkbox is always displayed next to a visible label.
107
111
108
112
### Checkbox with help text
109
113
110
-
In cases where the checkbox requires additional context, you can display this information as help text below the checkbox control and label. This can help keep checkbox labels concise. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component.
111
-
114
+
Use Checkbox with Help Text in cases where the checkbox requires additional context. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component.
112
115
<LivePreviewscope={{Checkbox}}language="jsx">
113
116
{`<Checkbox id="enabled" value="enabled" name="enabled" helpText="Determines if certificate validation is performed on all Twilio originated requests">
114
117
Enable SSL certificate validation
@@ -117,17 +120,29 @@ In cases where the checkbox requires additional context, you can display this in
117
120
118
121
### Required checkbox
119
122
120
-
When a checkbox is requiredto be checked, a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user.
123
+
Use the `required` prop to show a required indicator alongside the label when a checkbox is required to be checked. Ensure the label text includes wording that successfully describes the requirement to the user that they should check the box.
You can provide additional information about an individual item by adding a non-string element as a suffix. The suffix can be any non-string element that is not interactive.
Multiple checkboxes and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any checkboxes or other content.
145
+
Group related checkboxes using a common group component. The group legend should come first to clearly describe the set of options.
@@ -145,7 +160,7 @@ Multiple checkboxes and their labels are grouped together with a common group co
145
160
146
161
### Checkbox group with help text
147
162
148
-
You can provide additional information about the group with the use of help text. Help text can appear after the group label but before the first group member. Each item in the group may also provide their own, individual help text.
163
+
Use help text to give more context about a Checkbox group. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component. Individual checkboxes can also include their ownhelp text if needed.
@@ -178,33 +193,51 @@ You can provide additional information about the group with the use of help text
178
193
</CheckboxGroup>`}
179
194
</LivePreview>
180
195
181
-
### Checkbox with suffix
196
+
### Required Checkbox Group
182
197
183
-
You can provide additional information about an individual item by adding a non-string element as a suffix. The suffix can be any non-string element that is not interactive.
198
+
Use a required indicator alongside the label when at least one item from the Checkbox Group is required to be checked.
Use a horizontal layout for Checkbox Group when options can be placed next to each other in a logical order and the labels for each option are shorter than 3 words.
I declare the information provided above is accurate. I acknowledge that Twilio will process the information provided above for the purpose of identity verification, and will be sharing it with my local telecomm providers or authorities where required by local law. I understand that Twilio phone numbers may be taken out of service for inaccurate or false information.
@@ -213,8 +246,7 @@ You can provide additional information about an individual item by adding a non-
213
246
214
247
### Internationalization
215
248
216
-
To internationalize a checkbox, simply pass different text to the checkbox and checkbox group. The only exception to this is the required dot in the legend of a required checkbox group. To change the required dot's text, use the `i18nRequiredLabel` prop.
217
-
249
+
To internationalize a checkbox, pass different text to Checkbox and Checkbox Group. The only exception to this is the required dot in the legend of a required Checkbox Group. To change the required dot's text, use the `i18nRequiredLabel` prop.
@@ -244,17 +276,17 @@ To internationalize a checkbox, simply pass different text to the checkbox and c
244
276
245
277
### Unchecked, checked and indeterminate
246
278
247
-
The default state of a checkbox indicates that the control is unchecked, or not selected. When a checkbox is clicked or the spacebar is pressed when focused, the checkbox will become checked. Doing so again will place the checkbox back into the unchecked state. A checkbox can be placed into a pre-checked state by setting the `checked` property.
279
+
By default, checkboxes are unchecked. Clicking or pressing the spacebar toggles the checked state on or off. You can set a checkbox to be pre-checked using the `checked` property.
248
280
249
-
The third state a checkbox can appear in is the indeterminate state. This is to indicate that a checkbox is neither checked nor unchecked. This is useful when dealing with related groups of checkboxes that have a dependent relationship, for example, a select all feature.
281
+
Checkboxes also support an indeterminate state, used when the checkbox is neither fully checked nor unchecked—like in a “Select all” scenario where only some items are selected.
Use a disabled checkbox to indicate that a particular option cannot be interacted with or can be safely ignored.
289
+
Use a disabled Checkbox to indicate that a particular option cannot be interacted with or can be safely ignored.
258
290
259
291
<LivePreviewscope={{Checkbox}}language="jsx">
260
292
{`<Checkbox
@@ -268,55 +300,30 @@ Use a disabled checkbox to indicate that a particular option cannot be interacte
268
300
</Checkbox>`}
269
301
</LivePreview>
270
302
271
-
### Required checkbox group
272
-
273
-
When at least one item from the checkbox group is required, a required indicator should be displayed alongside the group legend. The group help text should be used to describe the requirement.
legend="Select the clients you would like to test."
303
311
disabled
304
312
>
305
-
<Checkbox id="voice" value="voice">
306
-
Voice
307
-
</Checkbox>
308
-
<Checkbox id="fax" value="fax">
309
-
Fax
313
+
<Checkbox id="apple_mail" value="apple_mail">
314
+
Apple Mail
310
315
</Checkbox>
311
-
<Checkbox id="sms" value="sms">
312
-
SMS
316
+
<Checkbox id="outlook" value="outlook">
317
+
Outlook
313
318
</Checkbox>
314
319
</CheckboxGroup>`}
315
320
</LivePreview>
316
321
317
-
### Checkbox group with an inline error
322
+
### Checkbox group with an error
318
323
319
-
If the selected options don't pass the group validation requirements, display an inline error message below the checkbox group.
324
+
If the selected options don't pass the group validation requirements, use the `errorText` prop to show an error message.
325
+
326
+
Focus the error text on how users can fix the issue. For additional guidance on how to compose error messages, refer to the [Error state pattern](/patterns/error-state).
@@ -339,23 +346,19 @@ If the selected options don't pass the group validation requirements, display an
339
346
340
347
Checkboxes and Checkbox Groups must have a visible label.
341
348
342
-
- Aim for no more than 3 words. If the label must be longer and space is limited, wrap the label.
349
+
- Aim for no more than 3 words.
343
350
- Structure each checkbox label similarly. For example, make each checkbox a noun.
344
351
- Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".
345
352
346
-
Checkbox labels should reflect what happens if the box is checked. Avoid situations where the user must check a box to negate something. For example, "Don't send message."
347
-
348
-
Avoid constructing the legend and label text to read as a sentence.
353
+
Checkbox labels should reflect what happens if the box is checked. Avoid situations where the user must check a box to negate something. For example, "Don't send messages."
349
354
350
-
Use [Help Text](/components/help-text)to give additional context and provide enough information to avoid errors. Consider using Help Text to indicate to users that they can select multiple options. Limit Help Text to 1-2 sentences.
355
+
Use the `helpText` prop to give additional context and provide enough information to avoid errors. Consider using help text to indicate to users that they can select multiple options. Limit help text to 1-2 sentences.
351
356
352
357
To support internationalization, avoid starting a sentence with the legend and using the field to finish it since sentence structures vary across languages. For example, use "Phone Number capabilities", not "Phone Number capabilities include:".
353
358
354
-
### Validation and errors
359
+
### Validation
355
360
356
-
Validate form fields on form submission. Don't validate each item in a group, treat validation on the group as a whole.
357
-
358
-
Use inline error text to explain how to fix an error. Because space is typically limited, focus the error text on how users can fix the issue. For additional guidance on how to compose error messages, refer to the [error state pattern](/patterns/error-state).
361
+
Validate a checkbox or a checkbox group on form submission. Don't validate each item in a group, treat validation on the group as a whole. For additional guidance on how to validate form fields, refer to our [Form pattern validation](/patterns/form#validation) guidelines.
359
362
360
363
## Do and don't
361
364
@@ -372,22 +375,6 @@ Use inline error text to explain how to fix an error. Because space is typically
372
375
<Donttitle="Don't"body="Don't save or persist a user's choice upon checking a checkbox." />
373
376
</DoDont>
374
377
375
-
<DoDont>
376
-
<Do
377
-
title="Do"
378
-
body="Keep help text and error text concise and simple. If you need to use more than 2 sentences to explain a field, link out to supporting docs or trigger a popover instead."
379
-
/>
380
-
<Donttitle="Don't"body="Don't use more than 2 sentences in help text or error text." />
381
-
</DoDont>
382
-
383
-
<DoDont>
384
-
<Do
385
-
title="Do"
386
-
body="Include a visible label on every checkbox. Include a visible legend for the entire group of checkboxes."
0 commit comments