Skip to main content

CheckboxGroup

Allows a user to select one or multiple items from a list.

github
View source code
figma
View design

Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.
Component Guide
import { CheckboxGroup } from '@uhg-abyss/web/ui/CheckboxGroup';

Using useForm and FormProvider simplifies form management by providing out-of-the-box validation, form state handling, and performance optimizations, leveraging the power of react-hook-form.

useState​

Using the useState hook gets values from the component state.

CheckboxGroup.Column​

The checkbox group is organized into CheckboxGroup.Column subcomponents. Each Checkbox is required to be wrapped in a CheckboxGroup.Column when using CheckboxGroup.

CheckboxGroup.SelectAll​

Use the CheckboxGroup.SelectAll component to create a checkbox for selecting all options. It must live as a child of CheckboxGroup.Column.

Validation​

Form Compatibility
useState
useForm

Use the validators prop to pass in required or custom validations like minimum selection amount.

Tip

The default error message when required is true is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form.

Label​

Use the label prop to add a custom checkbox group label. If you do not want to display any label, use prop hideLabel.

Helper​

Use the helper prop to display a help icon next to the label. Simply passing a string value will render the default helper, a Tooltip containing that string. The helper can be customized by passing in a node. It is recommended to use either a Tooltip or a Popover. See When should I use a Tooltip vs. a Popover? for more information on best practices regarding the two.

Disabled​

Use the isDisabled prop to disable the entire group.

Multi-line wrapping​

The label for each checkbox button, has a maximum width of 743px. After that, the text will wrap.

Subtext​

Use the subText prop to display helpful information related to the input field. The prop can take a string or an object in the form of {text: string; position: 'above' | 'below'} which allows you to decide if you want to place the subText above or below the input field.

Error message​

Form Compatibility
useState
useForm

Use the errorMessage prop to insert a custom error message below the checkbox group.

useState only

The errorMessage prop does not work with useForm and is only applicable within our form input components when useState is being utilized. See the useForm Docs for example use cases with useForm.

Success message​

Form Compatibility
useState
useForm

Use the successMessage prop to display a custom success message below the input field. To provide a single success message across all form input components using useForm/FormProvider, you can provide successMessage to FormProvider as shown here.

CheckboxGroup Props​

Name
Type
DefaultRequiredA11yDescription
children
string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
The content of the CheckboxGroup; must be CheckboxGroup.Column components
className
string | undefined
CSS class name to apply to each element within the component
css
CSSProperties | Partial<Record<"abyss-checkbox-group-label-container" | "abyss-checkbox-group-label" | "abyss-checkbox-group-root" | "abyss-checkbox-group-container" | "abyss-checkbox-group-sub-text" | "abyss-checkbox-group-descriptors", CSSProperties>> | undefined
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string | undefined
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean | undefined
false
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
errorMessage
string | undefined
Error message to display for the input. Only used when not in a FormProvider.
errorMessage should not exist in useForm mode.
helper
string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
Helper element next to label
hiddenFrom
Breakpoint | undefined
When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideLabel
boolean | undefined
false
If true, hides the label visually while keeping it accessible to screen readers.
highlighted
boolean | undefined
false
If true, the input field will be highlighted
isDisabled
boolean | undefined
false
If true, the input will be disabled
isRequired
boolean | undefined
Whether the input is required. Only used when not in a FormProvider.
isRequired should not exist in useForm mode.
label
string
The label for the input; associated with it so screen readers announce it as the input's accessible name.
model
string | undefined
model should not exist in useState mode.
Model name for form validation. Only used when in a FormProvider.
onBlur
FocusEventHandler<HTMLInputElement> | undefined
Callback function executed when the input is blurred
onChange
((values: string[]) => void) | undefined
Callback function executed when the CheckboxGroup value changes
onFocus
FocusEventHandler<HTMLInputElement> | undefined
Callback function executed when the input is focused
slotProps
Partial<Record<ToSlotKey<{ root: LeafSlotDef<("div" | "fieldset")[], undefined>; labelContainer: LeafSlotDef<"div", "checkbox-group-label-container">; label: LeafSlotDef<"div", undefined>; container: LeafSlotDef<...>; descriptors: LeafSlotDef<...>; subText: WrappedSlotDef<...>; }, "checkbox-group">, SlotPropsLeafVal...
Props to pass to individual internal slots of the component.
See slotProps for more information
subText
string | { text: string; position: SubTextPosition; } | undefined
Additional descriptive text for the input
successMessage
string | undefined
Success message to display for the input
validators
RegisterOptions | undefined
validators should not exist in useState mode.
Validators for the input. Only used when in a FormProvider.
value
((string | number | readonly string[]) & string[]) | undefined
The value of the input. Only used when not in a FormProvider.
value should not exist in useForm mode.
visibleFrom
Breakpoint | undefined
When defined, the component is hidden until the screen width reaches the specified breakpoint.

CheckboxGroup.SelectAll Props​

Name
Type
DefaultA11yDescription
className
string | undefined
CSS class name to apply to each element within the component
css
CSSProperties | Partial<Record<"abyss-checkbox-group-select-all-root" | "abyss-checkbox-group-select-all-checkbox" | "abyss-checkbox-group-select-all-icon" | "abyss-checkbox-group-select-all-label", CSSProperties>> | undefined
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string | undefined
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean | undefined
false
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
hiddenFrom
Breakpoint | undefined
When defined, the component is hidden once the screen width reaches the specified breakpoint.
label
string | undefined
'Select All'
The label of the "select all" checkbox; used as its accessible name for screen readers.
slotProps
Partial<Record<ToSlotKey<{ root: LeafSlotDef<"div", "checkbox-group-select-all-root">; checkbox: LeafSlotDef<("input" | "span")[], "checkbox-group-select-all-checkbox">; icon: LeafSlotDef<...>; label: LeafSlotDef<...>; }, "checkbox-group">, SlotPropsLeafValue>> | undefined
visibleFrom
Breakpoint | undefined
When defined, the component is hidden until the screen width reaches the specified breakpoint.

CheckboxGroup.Column Props​

Name
Type
DefaultDescription
children
string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
The elements the checkbox group column wraps
className
string | undefined
CSS class name to apply to each element within the component
css
CSSProperties | Partial<Record<"abyss-checkbox-group-column", CSSProperties>> | undefined
Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
See CSS Prop Styling for more information
data-testid
string | undefined
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
disableDefaultProviderProps
boolean | undefined
false
If set to true, the component will not use the DefaultPropsProvider values.

If you aren’t using the DefaultPropsProvider, this prop can be ignored.
hiddenFrom
Breakpoint | undefined
When defined, the component is hidden once the screen width reaches the specified breakpoint.
slotProps
Partial<Record<"checkbox-group-column", SlotPropsLeafValue>> | undefined
visibleFrom
Breakpoint | undefined
When defined, the component is hidden until the screen width reaches the specified breakpoint.

CheckboxGroup Classes​

Class NameDescription
.abyss-checkbox-group-containerCheckbox group container
.abyss-checkbox-group-descriptorsDescriptor element
.abyss-checkbox-group-labelLabel element
.abyss-checkbox-group-label-containerLabel element container
.abyss-checkbox-group-rootCheckbox group root element
.abyss-checkbox-group-sub-textSubtext element

CheckboxGroup.SelectAll Classes​

Class NameDescription
.abyss-checkbox-group-select-all-checkboxSelect All checkbox input element
.abyss-checkbox-group-select-all-iconSelect All checkbox icon element
.abyss-checkbox-group-select-all-labelSelect All checkbox label element
.abyss-checkbox-group-select-all-rootSelect All root

CheckboxGroup.Column Classes​

Class NameDescription
.abyss-checkbox-group-columnThe elements the checkbox group column wraps

ARIA settings on <fieldset>​

The CheckboxGroup component applies the following ARIA attributes to the <fieldset> element:

  • aria-labelledby: Added since <legend> is not immediate child of <fieldset>. As a result, <fieldset> will not be correctly labelled (all screen readers).
  • aria-required: Used to indicate the group requires at least one checkbox selected, not individual checkboxes. Set totrue when the isRequired prop.
  • aria-invalid: Used to indicate the group has any invalid checkboxes. It is set to true when there are errors in the group.
  • aria-describedBy: This attribute is used on <fieldset> to associate subText and error messages with the group, rather than (all the) individual checkboxes. The intent is to separate errors for any specific checkbox from those that apply to the group.

Accepted BrAT Variant Behaviors​

Depending on screen reader (and browser), the settings applied to <fieldset> are not always announced reliably.

  • JAWS announces all <fieldset> information correctly by default

  • NVDA announces all <fieldset> information correctly in forms mode

    • NVDA does not trigger forms mode by default when entering checkboxes

    • NVDA Browse mode behavior

      • Announces <legend> (group name)
      • Does not announce required, invalid, subtext and error messages

  • VoiceOver (Mac) announces group label

    • Does not reliably announce updates to aria-describedby, so error messages may be left out
    • Does not announce required (aria-required) or invalid (aria-invalid)

Component Tokens​

Tip

Click on the token row to copy the token to your clipboard.

CheckboxGroup Tokens​

Token NameValue
checkbox-group.color.border.columns-container.error
#990000
checkbox-group.color.border.columns-container.success
#007000
checkbox-group.border-radius.all.columns-container.error
4px
checkbox-group.border-width.all.columns-container.error
1px
checkbox-group.spacing.gap.horizontal.column
8px
checkbox-group.spacing.gap.vertical.columns-container
8px
checkbox-group.spacing.padding.all.columns-container
8px

Checkbox Tokens​

Token NameValue
checkbox.color.surface.control.enabled.default.rest
#FFFFFF
checkbox.color.surface.control.enabled.default.hover
#FFFFFF
checkbox.color.surface.control.enabled.default.active
#FFFFFF
checkbox.color.surface.control.enabled.selected.rest
#196ECF
checkbox.color.surface.control.enabled.selected.hover
#004BA0
checkbox.color.surface.control.enabled.selected.active
#002677
checkbox.color.surface.control.disabled.default
#CBCCCD
checkbox.color.surface.control.disabled.selected
#7D7F81
checkbox.color.border.control.enabled.default.rest
#7D7F81
checkbox.color.border.control.enabled.default.hover
#4B4D4F
checkbox.color.border.control.enabled.default.active
#323334
checkbox.color.border.control.disabled.default
#7D7F81
checkbox.color.text.label
#4B4D4F
checkbox.color.icon
#FFFFFF
checkbox.border-radius.all.control
4px
checkbox.border-width.all.control
2px
checkbox.sizing.all.icon
20px
checkbox.spacing.gap.vertical.container
8px
checkbox.spacing.gap.horizontal.control-label-container
8px

Header Tokens​

Token NameValue
input-header.color.text.label
#4B4D4F
input-header.color.text.hint
#4B4D4F
input-header.color.icon.info.rest
#196ECF
input-header.color.icon.info.hover
#004BA0
input-header.color.icon.info.active
#002677
input-header.sizing.all.icon
24px
input-header.spacing.gap.horizontal.container
4px
input-header.spacing.gap.horizontal.label
4px
input-header.spacing.gap.vertical.content
4px
input-header.spacing.padding.top.content
2px

Validation Tokens​

Token NameValue
input-validation.color.surface.container
#FFFFFF
input-validation.color.text.error
#990000
input-validation.color.text.success
#007000
input-validation.color.icon.error
#990000
input-validation.color.icon.success
#007000
input-validation.sizing.all.icon
20px
input-validation.spacing.gap.horizontal.container
4px
Table of Contents