Checkbox
Checkbox
and CheckboxGroup
allow users to select or deselect a specific option. A checkbox can stand alone to control a single option, or form part of a checkbox group to control multiple options.
A single checkbox can be either selected or deselected.
CheckboxGroup
allows selection of one or more values from a given set of choices. They can be aligned horizontally or vertically. By default, the group is aligned vertically.
- Do not truncate checkbox text descriptions as this can hide important content relevant to the user’s workflow. Consider shortening or rewording the label if space is limited.
- The checkbox should always be placed left aligned to the text.
By default, a checkbox group is aligned vertically. To align horizontally, set direction="horizontal"
.
Keep text as clear and concise as possible in the horizontal orientation.
By default, a checkbox group in a horizontal alignment wraps onto the next line as the viewport size changes if they don’t fit within a container.
To configure checkbox groups to maintain a horizontal alignment but allow text wrapping, set the prop wrap=false
.
When a checkbox option is neither selected nor deselected, it is indeterminate. This is a third, separate state.
A checkbox with the prop indeterminate={true}
will display an indeterminate icon. The most common use is a nested checkbox group with a hierarchy of selections. When the group contains a mix of selected and unselected children, the parent will show an indeterminate state.
A disabled checkbox is not interactive or focusable.
You can disable a checkbox by setting disabled={true}
.
Use a disabled state for checkboxes that have permissions, dependencies or pre-requisites. For example, a checkbox in a form may be disabled because the user has not yet completed an earlier section of the form.
If a disabled checkbox's text description contains information that is valuable to the user, consider using a read-only checkbox instead.
A read-only checkbox permits the user to only read or copy the text description, but not edit the text or change the state of the checkbox.
A checkbox with the prop readOnly={true}
will suppress all functionality along with displaying read-only styling.
Note: Screen reader support for read-only checkboxes is limited. You can work around this by adding visual or non-visual labels.
Read-only checkboxes are navigable using keyboard shortcuts. This means that, unlike disabled checkboxes, users can interact with the text description. Use a read-only checkbox instead of a disabled checkbox when the text description contains information that is valuable to the user.
Indicate an error state by setting the validationStatus
prop to "error". Use when you want to alert the user to a critical issue related to the checkbox.
Indicate a warning state by setting the validationStatus
prop to "warning". Use when you want to alert the user to a non-critical issue related to the checkbox.
- When used in a group, use
validationStatus
on the group rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. - Avoid using
validationStatus
when a checkbox is disabled. If provided, disabled functionality and styling will take precedence over any validation status styling.
Checkbox supports long text descriptions. If text wraps to multiple lines, it aligns to the top of the checkbox.
You can wrap checkbox groups in a form field when it’s displayed within a form. This provides functionality built into FormField
for increased accessibility.
For more information, refer to the form pattern.
You can add a description to a checkbox using a StackLayout
in the label
prop.
A single checkbox can be either selected or deselected.
CheckboxGroup
allows selection of one or more values from a given set of choices. They can be aligned horizontally or vertically. By default, the group is aligned vertically.
- Do not truncate checkbox text descriptions as this can hide important content relevant to the user’s workflow. Consider shortening or rewording the label if space is limited.
- The checkbox should always be placed left aligned to the text.
By default, a checkbox group is aligned vertically. To align horizontally, set direction="horizontal"
.
Keep text as clear and concise as possible in the horizontal orientation.
By default, a checkbox group in a horizontal alignment wraps onto the next line as the viewport size changes if they don’t fit within a container.
To configure checkbox groups to maintain a horizontal alignment but allow text wrapping, set the prop wrap=false
.
When a checkbox option is neither selected nor deselected, it is indeterminate. This is a third, separate state.
A checkbox with the prop indeterminate={true}
will display an indeterminate icon. The most common use is a nested checkbox group with a hierarchy of selections. When the group contains a mix of selected and unselected children, the parent will show an indeterminate state.
A disabled checkbox is not interactive or focusable.
You can disable a checkbox by setting disabled={true}
.
Use a disabled state for checkboxes that have permissions, dependencies or pre-requisites. For example, a checkbox in a form may be disabled because the user has not yet completed an earlier section of the form.
If a disabled checkbox's text description contains information that is valuable to the user, consider using a read-only checkbox instead.
A read-only checkbox permits the user to only read or copy the text description, but not edit the text or change the state of the checkbox.
A checkbox with the prop readOnly={true}
will suppress all functionality along with displaying read-only styling.
Note: Screen reader support for read-only checkboxes is limited. You can work around this by adding visual or non-visual labels.
Read-only checkboxes are navigable using keyboard shortcuts. This means that, unlike disabled checkboxes, users can interact with the text description. Use a read-only checkbox instead of a disabled checkbox when the text description contains information that is valuable to the user.
Indicate an error state by setting the validationStatus
prop to "error". Use when you want to alert the user to a critical issue related to the checkbox.
Indicate a warning state by setting the validationStatus
prop to "warning". Use when you want to alert the user to a non-critical issue related to the checkbox.
- When used in a group, use
validationStatus
on the group rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. - Avoid using
validationStatus
when a checkbox is disabled. If provided, disabled functionality and styling will take precedence over any validation status styling.
Checkbox supports long text descriptions. If text wraps to multiple lines, it aligns to the top of the checkbox.
You can wrap checkbox groups in a form field when it’s displayed within a form. This provides functionality built into FormField
for increased accessibility.
For more information, refer to the form pattern.
You can add a description to a checkbox using a StackLayout
in the label
prop.
A single checkbox can be either selected or deselected.
CheckboxGroup
allows selection of one or more values from a given set of choices. They can be aligned horizontally or vertically. By default, the group is aligned vertically.
- Do not truncate checkbox text descriptions as this can hide important content relevant to the user’s workflow. Consider shortening or rewording the label if space is limited.
- The checkbox should always be placed left aligned to the text.
By default, a checkbox group is aligned vertically. To align horizontally, set direction="horizontal"
.
Keep text as clear and concise as possible in the horizontal orientation.
By default, a checkbox group in a horizontal alignment wraps onto the next line as the viewport size changes if they don’t fit within a container.
To configure checkbox groups to maintain a horizontal alignment but allow text wrapping, set the prop wrap=false
.
When a checkbox option is neither selected nor deselected, it is indeterminate. This is a third, separate state.
A checkbox with the prop indeterminate={true}
will display an indeterminate icon. The most common use is a nested checkbox group with a hierarchy of selections. When the group contains a mix of selected and unselected children, the parent will show an indeterminate state.
A disabled checkbox is not interactive or focusable.
You can disable a checkbox by setting disabled={true}
.
Use a disabled state for checkboxes that have permissions, dependencies or pre-requisites. For example, a checkbox in a form may be disabled because the user has not yet completed an earlier section of the form.
If a disabled checkbox's text description contains information that is valuable to the user, consider using a read-only checkbox instead.
A read-only checkbox permits the user to only read or copy the text description, but not edit the text or change the state of the checkbox.
A checkbox with the prop readOnly={true}
will suppress all functionality along with displaying read-only styling.
Note: Screen reader support for read-only checkboxes is limited. You can work around this by adding visual or non-visual labels.
Read-only checkboxes are navigable using keyboard shortcuts. This means that, unlike disabled checkboxes, users can interact with the text description. Use a read-only checkbox instead of a disabled checkbox when the text description contains information that is valuable to the user.
Indicate an error state by setting the validationStatus
prop to "error". Use when you want to alert the user to a critical issue related to the checkbox.
Indicate a warning state by setting the validationStatus
prop to "warning". Use when you want to alert the user to a non-critical issue related to the checkbox.
- When used in a group, use
validationStatus
on the group rather than the individual controls. Any status provided to the group will take precedence over the statuses applied directly to the nested controls. - Avoid using
validationStatus
when a checkbox is disabled. If provided, disabled functionality and styling will take precedence over any validation status styling.
Checkbox supports long text descriptions. If text wraps to multiple lines, it aligns to the top of the checkbox.
You can wrap checkbox groups in a form field when it’s displayed within a form. This provides functionality built into FormField
for increased accessibility.
For more information, refer to the form pattern.
You can add a description to a checkbox using a StackLayout
in the label
prop.