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
      label="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.

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.

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
errorMessage	never | string | undefined	-	-	errorMessage should not exist in useForm mode. Error message to display for the input. Only used when not in a FormProvider.
highlighted	boolean | undefined	false	-	If true, the input field will be highlighted
isChecked	boolean | undefined	false	-	If true, the Toggle is checked
isDisabled	boolean | undefined	false	-	If true, the input will be disabled
isRequired	never | boolean | undefined	-	-	isRequired should not exist in useForm mode. Whether the input is required. Only used when not in a FormProvider.
label	string | { text: string; position: 'left' | 'right'; }	-		The label for the Toggle
model	string | never | undefined	-	-	Model name for form validation. Only used when in a FormProvider. model should not exist in useState mode.
onBlur	React.FocusEventHandler<HTMLInputElement> | undefined	-	-	Callback function executed when the input is blurred
onChange	React.ChangeEventHandler<HTMLInputElement> | undefined	-	-	Callback function executed when the input value changes
onFocus	React.FocusEventHandler<HTMLInputElement> | undefined	-	-	Callback function executed when the input is focused
showIcons	boolean | undefined	true	-	If true, the Toggle thumb will display an icon
subText	string | { text: string; position: SubTextPosition } | undefined	-	-	Additional descriptive text for the input
validators	RegisterOptions | never | undefined	-	-	Validators for the input. Only used when in a FormProvider. validators should not exist in useState mode.

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

Toggle.types.ts

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

Tip

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

Toggle Tokens

Search 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

Input Tokens

Search 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

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