Skip to main contentPrimer

CheckboxGroup

CheckboxGroup renders a set of Checkboxes.

Page navigation navigation

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

Accessibility and usability expectations

Checkboxes are most commonly used as part of a CheckboxGroup.

Presentation

Cognition

  • A CheckboxGroup must have a visible group label that provides context
  • If a selection from a CheckboxGroup is required, this must be indicated in the group label, ideally using clear text such as "(required)" rather than an asterisk alone. 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 users understand its purpose
  • Checkbox labels should appear to the right of the checkbox

Vision

  • All text, group label, caption, option labels, error and success messages, must meet the minimum contrast ratio of 4.5:1
  • The checkbox border must have a minimum contrast ratio of 3:1 against the background
  • Checkbox focus styles must have a minimum contrast ratio of 3:1 against the background
  • A checkbox must have a distinct checked state that does not rely on color alone

Mobility

  • The clickable target area of a checkbox must be at least 24 by 24 CSS pixels to support users with limited dexterity

Adaptability

  • Text must be resizable up to 200% and remain readable
  • Layout must reflow at a 320px viewport or 400% zoom without requiring horizontal scrolling
  • Text spacing must be adjustable without loss of content or functionality

Interaction

Keyboard

  • Unless disabled, a checkbox must be focusable using the Tab key
  • Pressing Space must check or uncheck the focused checkbox
  • A checkbox must not trap keyboard focus
  • A checkbox must not trigger a change of context when focused or activated

Engineering for AT Compatibility

Screen reader

  • Each checkbox must have an associated <label> to provide an accessible name
  • Additional instructions or requirements should be programmatically associated using aria-describedby
  • Captions or error messages for individual checkbox should be associated with the <input>
  • For group-level messaging, include the message directly within the <legend> to ensure it is read correctly by screen readers
  • The checkbox must have the ARIA role of checkbox
  • The checked state must be conveyed using aria-checked or the native checked attribute
  • If disabled, the disabled state must be conveyed using aria-disabled="true" or the native disabled attribute

Speech recognition

  • The accessible name must include the visible text label so users can activate the checkbox using voice commands that match the label

Built-in accessibility features

  • The text, checkbox border, and, custom focus style meet minimum contrast requirements
  • The checkbox must have a distinct checked state that does not rely solely on color
  • The checkbox in a CheckboxGroup 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 checkbox convey the correct role and selected state to screen readers and has the correct keyboard behavior
  • 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 CheckboxGroup 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 CheckboxGroup 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 checkbox 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