import { CheckboxGroup } from '@uhg-abyss/web/ui/CheckboxGroup';useForm (recommended)
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
Use the validators prop to pass in required or custom validations like minimum selection amount.
Note: 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
Use the errorMessage prop to insert a custom error message below the checkbox group.
Note: 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
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 | Default | Required | Description |
|---|---|---|---|---|
children | React.ReactNode | - | - | The content of the CheckboxGroup; must be CheckboxGroup.Column components |
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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 | never | - | - | Error message to display for the input. Only used when not in a FormProvider. errorMessage should not exist in useForm mode. |
helper | React.ReactNode | - | - | Helper element next to label |
hideLabel | boolean | false | - | If true, the label will be visually hidden |
highlighted | boolean | false | - | If true, the input field will be highlighted |
isDisabled | boolean | false | - | If true, the input will be disabled |
isRequired | boolean | never | - | - | 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 | |
model | never | string | - | - | model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider. |
onBlur | React.FocusEventHandler<HTMLInputElement> | - | - | Callback function executed when the input is blurred |
onChange | (values: string[]) => void | - | - | Callback function executed when the CheckboxGroup value changes |
onFocus | React.FocusEventHandler<HTMLInputElement> | - | - | Callback function executed when the input is focused |
subText | string | { text: string; position: SubTextPosition; } | - | - | Additional descriptive text for the input |
successMessage | string | - | - | Success message to display for the input |
validators | never | RegisterOptions | - | - | validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider. |
value | ValueType | never | - | - | The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode. |
Below are the link(s) to the relevant GitHub type files:
Abyss.d.tsCheckboxGroup.SelectAll Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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. |
label | string | 'Select All' | - | The label of the "select all" checkbox |
Below are the link(s) to the relevant GitHub type files:
CheckboxGroup.Column Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
children | React.ReactNode | - | - | The elements the checkbox group column wraps |
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
disableDefaultProviderProps | boolean | 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. |
Below are the link(s) to the relevant GitHub type files:
CheckboxGroup Classes
| Class Name | Description |
|---|---|
| .abyss-checkbox-group-root | Checkbox group root element |
| .abyss-checkbox-group-label-container | Label element container |
| .abyss-checkbox-group-label | Label element |
| .abyss-checkbox-group-container | Checkbox group container |
| .abyss-checkbox-group-descriptors | Descriptor element |
| .abyss-checkbox-group-sub-text | Subtext element |
CheckboxGroup.SelectAll Classes
| Class Name | Description |
|---|---|
| .abyss-checkbox-group-select-all-root | Select All root |
| .abyss-checkbox-group-select-all-checkbox | Select All checkbox input element |
| .abyss-checkbox-group-select-all-icon | Select All checkbox icon element |
| .abyss-checkbox-group-select-all-label | Select All checkbox label element |
CheckboxGroup.Column Classes
| Class Name | Description |
|---|---|
| .abyss-checkbox-group-column | The 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 to
truewhen theisRequiredprop. - aria-invalid: Used to indicate the group has any invalid checkboxes. It is set to
truewhen 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
- Announces
-
-
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
Note: Click on the token row to copy the token to your clipboard.
CheckboxGroup Tokens
| Token Name | Value | |
|---|---|---|
| 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 Name | Value | |
|---|---|---|
| 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 Name | Value | |
|---|---|---|
| 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 Name | Value | |
|---|---|---|
| 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 |