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';

label

isDisabled

() => {
  const [isChecked, setIsChecked] = useState(true);

  return (
    <Checkbox
      label="I agree"
      isChecked={isChecked}
      onChange={(e) => setIsChecked(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 not clickable.
• 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.

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.

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.

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.

Styling note

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

Checkbox Props

Name	Type	Default	Required	A11y	Description
className	string | undefined				CSS class name to apply to each element within the component
css	CSSProperties | Partial<Record<"abyss-checkbox" | "abyss-checkbox-icon" | "abyss-checkbox-label" | "abyss-checkbox-root", 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
isChecked	boolean | undefined	false			If true, the Checkbox is checked
isDisabled	boolean | undefined	false			If true, the input will be disabled
isIndeterminate	boolean | undefined	false			If true, the Checkbox is indeterminate
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	ChangeEventHandler<HTMLInputElement> | undefined				Callback function executed when the input value changes
onFocus	FocusEventHandler<HTMLInputElement> | undefined				Callback function executed when the input is focused
slotProps	Partial<Record<ToSlotKey<{ root: LeafSlotDef<"div", undefined>; checkbox: LeafSlotDef<"input", "checkbox">; icon: LeafSlotDef<"span", "checkbox-icon">; label: LeafSlotDef<...>; }, "checkbox">, SlotPropsLeafValue>> | undefined				Props to pass to individual internal slots of the component. See slotProps for more information
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 | (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.

Checkbox Classes

Class Name	Description
.abyss-checkbox	Checkbox input element
.abyss-checkbox-icon	Icon element
.abyss-checkbox-label	Label element
.abyss-checkbox-root	Checkbox root element

Checkbox Types

Adheres to the Checkbox WAI-ARIA design patternopens in a new window.

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.

• TPGi's Required Groupsopens in a new window
• Marking Supportopens in a new window

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 exampleopens in a new window.

Component Tokens

Tip

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

Checkbox Tokens

Search 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

Search 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

Search 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