Checkbox

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.

For guidance on using a Checkbox in a form, refer to our Form pattern guidelines.

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.

• 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.
• Checkbox must have a visible label.
• 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.

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, you should consider using the Switch component.

• A checkbox must have a visible label that is in close proximity to the control
• HTML checkboxes don't natively support the required attribute. In cases where a checkbox is required to be checked:
  • Display a required indicator
  • Ensure the label text includes wording that successfully describes the requirement to the user that they should check the box
• When in an error state, display an inline error message below the checkbox or checkbox group that clearly describes the error along with an icon that depicts the severity.
• 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.

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.

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.

To make a controlled checkbox, pass the checked and onChange props. You cannot use the defaultChecked prop in a controlled checkbox.

A checkbox is always displayed next to a visible label.

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.

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.

Group related checkboxes using a common group component. The group legend should come first to clearly describe the set of options.

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 own help text if needed.

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.

Use Checkbox Disclaimer if a user needs to agree to Terms of Service or something similar.

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.

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.

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.

Use a disabled checkbox group to indicate that all options cannot be interacted with, with each checkbox individually disabled.

If the selected options don't pass the group validation requirements, use the errorText prop to show an error message.

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.

Checkboxes and Checkbox Groups must have a visible label.

• Aim for no more than 3 words.
• Structure each checkbox label similarly. For example, make each checkbox a noun.
• Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

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."

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.

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:".

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 guidelines.

• Error state
• Form pattern
• Form Layout component
• Radio Group