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 { Toggle } from '@uhg-abyss/web/ui/Toggle';

isDisabled

showIcons

label

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

  return (
    <Toggle
      isChecked={isChecked}
      onChange={e => setChecked(e.target.checked)}
    />
  );
};

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.

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.

Disabled

Use the isDisabled property to disable the Toggle. The default is set to false.

Label

The label prop is required. The prop accepts either a string or an object of the form:

{
  text: string;
  position: 'left' | 'right';
}

The position property determines where the label will be displayed in relation to the toggle. The default value is 'right'.

Subtext

Use the subText prop to display helpful information related to the input field. The prop accepts either a string or an object of the form:

{
  text: string;
  position: 'above' | 'below';
}

The position property determines where the subtext will be displayed in relation to the input field. The default value is 'below'.

Error message (useState)

Form Compatibility

useState

useForm

Use the errorMessage prop to display a custom error message below the input field when using useState.

Toggle Props

Name	Type	Default	Required	Description
ariaLabel	string	-	-	Adds an aria-label to the Toggle. Use when label is an icon or abbreviation.
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.
isDisabled	boolean	false	-	If true, the Toggle will be disabled
label	React.ReactNode	-	-	The label for the Toggle
value	string	-		The value of the Toggle

Toggle Classes

Class Name	Description
.abyss-toggle-root	Toggle root element
.abyss-toggle-main-container	Toggle main element
.abyss-toggle-container	Toggle container for the visual elements
.abyss-toggle-input	Toggle input element
.abyss-toggle-thumb	Toggle thumb indicator
.abyss-toggle-thumb-icon	The icon inside the thumb
.abyss-toggle-label	Toggle label element
.abyss-toggle-sub-text	Toggle sub text element
.abyss-toggle-descriptors	Toggle descriptors root element

Adheres to the Switch WAI-ARIA design pattern.

Toggle at its core functions like a Switch.

Toggle is an on-off switch with two states. Switches are similar to checkboxes and toggle buttons, which can also serve as binary inputs.

One difference, however, is that switches can only be used for binary input while checkboxes and toggle buttons allow implementations the option of supporting a third middle state.

** Note: "On/Off" text not used in Toggle switch. **

Reduced Motion

Animations and transitions that have been changed when a user has prefers-reduced-motion set to reduced:

• transition between on/off state is removed

Keyboard Interactions

Key	Description
Tab	Moves focus to the first toggle item.
Space	When focus is on an item, changes the state of the switch.

Component Tokens

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

Search tokens

Toggle Tokens

Token Name	Value
toggle.color.icon.default.rest	#4B4D4F
toggle.color.icon.default.active	#000000
toggle.color.icon.default.hover	#323334
toggle.color.icon.default.disabled	#4B4D4F
toggle.color.icon.selected.rest	#196ECF
toggle.color.icon.selected.active	#002677
toggle.color.icon.selected.hover	#004BA0
toggle.color.icon.selected.disabled	#4B4D4F
toggle.color.surface.container.default.rest	#7D7F81
toggle.color.surface.container.default.active	#323334
toggle.color.surface.container.default.hover	#4B4D4F
toggle.color.surface.container.default.disabled	#CBCCCD
toggle.color.surface.container.selected.rest	#196ECF
toggle.color.surface.container.selected.active	#002677
toggle.color.surface.container.selected.hover	#004BA0
toggle.color.surface.container.selected.disabled	#CBCCCD
toggle.color.surface.thumb.default	#FFFFFF
toggle.color.surface.thumb.disabled	#7D7F81
toggle.color.text.label	#323334
toggle.border-radius.all.thumb	500px
toggle.border-radius.all.container	500px
toggle.sizing.all.icon.utility	16px
toggle.spacing.gap.horizontal.toggle-label	8px
toggle.spacing.padding.all.container	4px
toggle.spacing.padding.all.thumb	4px

Search tokens

Input Tokens

Token Name	Value
input.color.surface.field.default	#FFFFFF
input.color.surface.field.highlighted	#E5F8FB
input.color.surface.field.disabled	#F3F3F3
input.color.border.field.rest	#4B4D4F
input.color.border.field.hover.default	#196ECF
input.color.border.field.hover.error	#990000
input.color.border.field.hover.success	#007000
input.color.border.field.active.default	#004BA0
input.color.border.field.active.error	#990000
input.color.border.field.active.success	#007000
input.color.text.input	#4B4D4F
input.color.text.hint	#4B4D4F
input.color.text.required	#990000
input.color.icon.utility.rest	#4B4D4F
input.color.icon.utility.hover	#323334
input.color.icon.utility.active	#000000
input.color.icon.content	#323334
input.border-radius.all.field	4px
input.border-width.all.field.default	1px
input.border-width.all.field.active	3px
input.sizing.all.icon	20px
input.spacing.gap.vertical.container	8px
input.spacing.gap.horizontal.field	12px
input.spacing.gap.horizontal.input-indicator	2px
input.spacing.gap.horizontal.prefix-input	2px
input.spacing.gap.horizontal.suffix-clear	2px
input.spacing.padding.all.focus-container	2px
input.spacing.padding.horizontal.field	12px
input.spacing.padding.left.field	12px
input.spacing.padding.right.focus-field	44px

Search tokens

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