CheckboxGroup

Once a user checks an option from a CheckboxGroup, the result should not be saved or applied until the user has explicitly submitted their input using a "save" or "submit" button. See the saving pattern guidelines for more information. Alternative: you can use a ToggleSwitch to immediately toggle something on and off as long as it's not in the context of a bigger form that applies other input values when submited.

Accessibility and usability expectations

Checkboxes are most commonly used as part of a checkbox group.

A checkbox group must have a visible group label that provides context.

If a selection from a checkbox group is required, an indication must be included as part of the group label. Best practice is to use text as the indicator, such as "(required)". Whilst an asterisk is sufficient to meet accessibility requirements, it's meaning may not be understood by all users, and may be difficult to see by users with low vision.

Each checkbox must have a clear, descriptive, and permanently visible label so that users understand their purpose.

The checkbox label should appears to the right of the checkbox.

The text, including the group label, caption, option labels and error and success message, must meet the minimum contrast requirements of 4.5:1.

The border of a checkbox must have a minimum contrast ration of 3:1 against the background.

A checkbox must have a visible focus style. Instead of using the browser's default focus style, which can be difficult to see against certain backgrounds, a custom focus style should be implemented. A custom focus style must have a minimum contrast ratio of 3:1 against the background.

Checkboxes must have a distinct checked state that does not rely solely on colour.

The target size and spacing of a checkbox must be at least 24 by 24 css pixels.

The text must be resizable and the text spacing adjustable, and must remain readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels.

Unless a checkbox is disabled, each checkbox must by focusable using the Tab key, and pressing the Space will check and uncheck the focused checkbox.

A checkbox must not trap focus or initiate a change of context when focused or activated.

A group of checkboxes must either be contained within a <fieldset> and have a <legend> as the first child to provide the group label, or be contained within a role="group" and have an aria-labelledby to provide the group label.

Each checkbox must have an associated <label> to give it an accessible name that is announced by screen readers.

Additional instructions or requirements must be easily discoverable by screen reader users - in general, by having them programmatically associated with the <input> or <fieldset> using aria-describedby. A caption that applies to a checkbox is associated with the <input>. When a caption or error message that applies to the checkbox group is associated with the <fieldset>, it will not be announced by NVDA due to a known bug. A more robust solution is the include the caption or error message in the <legend>.

The accessible name of each checkbox must include the visible label so that that speech recognition users can activate a checkbox by saying the visible text label.

A checkbox must have the role of checkbox so that screen readers convey the correct type of control.

The checked state of a checkbox must be conveyed to screen readers so blind users knows if it is checked or not.

If a checkbox is disabled, the disabled state must be conveyed to screen readers.

Built-in accessibility features

The text, checkbox border and custom focus style meet minimum contrast requirements.

The checkboxes have a distinct checked state that does not rely solely on colour.

The checkboxes in a checkbox group have sufficient spacing to meet the minimum target and spacing size of 24 by 24 CSS pixels.

The text is resizable and the text spacing adjustable. The component reflows when zoomed or viewed at a width equivalent to 320 CSS pixels.

By default, the component renders a <fieldset> and <legend> to provide the grouping and group label, but can also use aria-labelledby and role="group".

The component renders a correctly associated pair of <label> and <input type="checkbox">. Using the the native <input type="checkbox"> ensures that the checkboxes convey the correct role and selected state to screen readers and has the correct keyboard behaviour.

The group caption, error message and success message is automatically associated with the <fieldset> using aria-describedby. Whilst this works in most screen readers, a bug in NVDA means that the accessible description is not automatically announced in NVDA when a checkbox receives focus.

Option captions are automatically associated with the with the relevant <input>.

When a checkbox is disabled, the disabled attribute is applied and the disabled state conveyed to screen readers.

When a checkbox is given the indeterminate state, aria-checked="mixed is applied and the state conveyed to screen readers.

Implementation requirements

Ensure the checkbox group has a visible group label that provides context. The simplest way to do this is to use a CheckboxGroup.Label. Alternatively, an aria-labelledby that references an external label can be applied to CheckboxGroup.

CheckboxGroup.Label has a visuallyHidden prop, but this should not be used.

When using an icon for a leading visual, note that the icon doesn't have a text alternative. They are purely visual, and not conveyed to screen readers. Don't rely on these icons alone to convey meaning – make sure that the text label of the radio button provides sufficient meaning on its own.

How to test the component

Integration tests

• The checkbox group has a visible group label that provides a descriptive accessible name
• Each checkbox has a clear and visible label that describes it's purpose
• If the checkbox includes a leading visual icon, the input's purpose is clear from the text alone

Component tests

• When a CheckboxGroup is given a CheckboxGroup.label, a <fieldset> containing a <legend> as the first child, is rendered
• When a CheckboxGroup has an aria-labelledby applied, instead of a CheckboxGroup.label, a <div> with a role="group" and an aria-labelledby is rendered instead of a <fieldset> and <legend>
• The component renders a correctly associated pair of <label> and <input type="checkbox">
• All text, including labels, captions, error and success messages, meets the minimum contrast requirements of 4.5:1
• The checkbox border, checked style and custom focus style meets the minimum contrast requirement of 3:1
• The checkboxes have sufficient spacing to meet the minimum target and spacing size of 24 by 24 CSS pixels
• The content remains readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels
• If there is option caption, it is associated with the appropriate <input> using aria-describedby
• If a checkbox is disabled, the disabled attribute is present
• If a checkbox is indeterminate, aria-checked="mixed" is present and conveyed to screen readers