Skip to main content

Checkbox

Used to mark an option as true/checked or false/not checked.

Submit feedback
Edit this page
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 { Checkbox } from '@uhg-abyss/web/ui/Checkbox';
() => {
  const [isChecked, setChecked] = useState(true);


  return (
    <Checkbox
      label="I agree"
      isChecked={isChecked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
};

States​

  • Default - The default checkbox is unchecked.
  • Checked - Use the isChecked prop to mark a checkbox as checked.
  • Disabled - Use the isDisabled prop to disable a checkbox. A disabled checkbox is unusable and unclickable.
  • Error Message - Use the errorMessage prop to display a custom error message below the checkbox.
  • Success Message - Use the successMessage prop to display a custom success message below the checkbox.
  • Hidden Label - Use the hideLabel prop to hide the label but retain screen reader accessibility.
  • Indeterminate - Use the isIndeterminate prop to set the checkbox as indeterminate, which overrides the checked prop. Do note, the isIndeterminate prop is part of a tri-state property that is unique to checkbox inputs. The indeterminate state should only be used in conjunction with a set of checkboxes like in 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.

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.

useState​

Using the useState hook gets values from the component state.

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.

Note: helper is right aligned to the parent container. The gap between label and helper is defined by space-between.

Checkbox Props

NameTypeDefaultRequiredDescription
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
See CSS Prop Styling for more information
data-testid
string
--
Suffix used to create a unique ID used for automated testing
See Component Testing for more information
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
isChecked
boolean
false
-
If true, the Checkbox is checked
isDisabled
boolean
false
-
If true, the input will be disabled
isIndeterminate
boolean
false
-
If true, the Checkbox is indeterminate
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
React.ChangeEventHandler<HTMLInputElement>
--
Callback function executed when the input value changes
onFocus
React.FocusEventHandler<HTMLInputElement>
--
Callback function executed when the input is focused
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.ts

Checkbox Classes

Class NameDescription
.abyss-checkbox-rootCheckbox root element
.abyss-checkboxCheckbox input element
.abyss-checkbox-iconIcon element
.abyss-checkbox-labelLabel element
.abyss-checkbox-flex-containerCheckbox outer flex container element
.abyss-checkbox-containerCheckbox container element
.abyss-checkbox-inputCheckbox input element
.abyss-checkbox-labelCheckbox label element

Checkbox Types

Adheres to the Checkbox WAI-ARIA design pattern.

The component's input wrapper has a role="radiogroup" attribute, which is essential for screen readers to identify the group of radio buttons and further allow the usage of aria-required and aria-invalid inside the component. For more details, please visit the following:

Although we've added role="radioGroup" to the checkbox wrapper, it serves the same purpose of allowing the usage of aria-required and aria-invalid attributes inside the component.

WAI-ARIA supports two types of checkbox widgets:

Dual-State Checkbox

The most common type of checkbox, allows the user to toggle between two choices: checked and not checked.

For more information, see the WAI-ARIA mixed checkbox example.

Component Tokens

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

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