Checkbox (New)

Used to choose multiple options from a short list of choices.

CheckboxNew replaces the existing Checkbox, which is now deprecated. While the latter remains available in the design system, please use CheckboxNew instead. Wherever possible, migrate away from the deprecated Checkbox to this component within your area of ownership.

Please follow the Pausing selected form components rollout guidance when using other new form elements.

Stable

Show details

A checkbox allows users to select multiple options from a short list of choices. It’s best used to give people the flexibility to pick more than one item without forcing a single decision.

Checkboxes can be used individually as a singular checkbox or as a group of checkboxes.

Anatomy

Anatomy summary lists and describes all the elements within a component (including nested components).

Element	Description	Optional?
1. Field label	Mandatory textual label for CheckboxGroup used to describe the form field to guide users in filling it.	No
2.Required or optional marker	Textual label for CheckboxGroup used to denote if a field is required or optional. Marker’s copy is not changeable.	Yes
3. Popover trigger	Used to display a Popover next to with more content explaining the context of a field. Used when Helper text is not sufficient.	Yes
4. Helper text	Additional CheckboxGroup description helping users provide the right input, if the field label is insufficient.	Yes
5. Field	Checkbox element that allows users to select multiple options out of several options.	No
6. Helper text	Additional description for individual Checkbox elements helping users provide the right input, if the field label is insufficient.	Yes
7. Form validation	Icon and text used when validating user form input to provide advice on fixing input errors and confirmation when they are addressed.	Yes

Variants

Variants contain different versions of the component depending on specific properties, such as state, size, color, optional iconography, etc.

State, Helper Text, Popovers, and Markers

All new form components have been constructed using sub-components meant to be shared across forms. For that reason, Checkbox can have other variants are created by altering the properties of the sub-components. Check Component dependencies section for a detailed explanation.

Checkbox without a label

This variant is intended for exceptional use cases and should not be treated as a standard checkbox pattern.

This variant should not be treated as a standard checkbox pattern. A checkbox without a visible label should only be used when the surrounding context already makes its purpose clear, for example, in data tables where each row includes a checkbox for selecting items and the column header or row content provides sufficient meaning.

Accessibility requirements become even more critical when a visible label is removed. An ariaLabel must always be provided so assistive technologies can correctly communicate the checkbox’s function to users, ensuring the control remains understandable and usable without a visual label.

Additionally removing the label removes access to supporting features such as Helper Text, Popovers, and the Markers. For this reason, this variant should only be used when the interaction remains clear and usable without these supporting elements.

Validation

Checkbox has two validation variants signifying whether there has been an error.

Checkbox

validation error

Checkbox

validation neutral

Component dependencies

This component is internally dependent on the following form sub-components:

Figma	Code
N/A	CheckboxGroup (Uses Legend, InputError, InputLabel and FormDescription )
formElement.labelGroup	Legend
formElement.checkboxGroup.items	N/A
formElement.checkbox.field	N/A (This is in CheckboxNew )
formElement.checkbox	CheckboxNew (Uses InputError, InputLabel and FormDescription )
formElement.validation	InputError
N/A	FormDescription
	InputLabel

Code sub-components

Refer to the code documentation for further information.

Figma sub-components

formElement.labelGroup

isDisabled false

formElement.labelGroup

isDisabled true

formElement.labelGroup

Property	Values	Default
↳ ✏️ defaultText Text	string	(default)
hasDefaultMarker Boolean	true \| false	false
popover Boolean	true \| false	false
✏️ fieldLabel Text	string	Field label
hasRequiredMarker Boolean	true \| false	false
hasOptionalMarker Boolean	true \| false	true
↳ ✏️ helperText Text	string	Optional helper text
helperText Boolean	true \| false	false
↳ helperLink Boolean	true \| false	false
isDisabled Variant	false \| true	false

formElement.checkbox

state indeterminate isChecked true isDisabled true

formElement.checkbox

state rest isChecked true isDisabled false

formElement.checkbox

state focus isChecked true isDisabled false

formElement.checkbox

state rest isChecked false isDisabled true

formElement.checkbox

state focus isChecked false isDisabled false

formElement.checkbox

state indeterminate isChecked true isDisabled false

formElement.checkbox

state rest isChecked false isDisabled false

formElement.checkbox

state rest isChecked true isDisabled true

formElement.checkbox

Property	Values	Default
state Variant	rest \| focus \| indeterminate	rest
isChecked Variant	false \| true	false
isDisabled Variant	false \| true	false