import { Toggle } from '@uhg-abyss/web/ui/Toggle';() => { 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.
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)
Use the errorMessage prop to display a custom error message below the input field when using useState.
Toggle 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-toggle-input" | "abyss-toggle-label" | "abyss-toggle-root" | "abyss-toggle-container" | "abyss-toggle-sub-text" | "abyss-toggle-descriptors" | "abyss-toggle-thumb" | "abyss-toggle-main-container" | "abyss-toggle-thumb-icon", 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. | |||
hiddenFrom | Breakpoint | undefined | When defined, the component is hidden once the screen width reaches the specified breakpoint. | |||
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 | boolean | undefined | Whether the input is required. Only used when not in a FormProvider. isRequired should not exist in useForm mode. | |||
label | string | { text: string; position: "left" | "right"; } | The label for the Toggle | |||
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 | |||
showIcons | boolean | undefined | true | If true, the Toggle thumb will display an icon | ||
slotProps | ToggleSlotPropsMap | undefined | Slot props for overriding internal elements | |||
subText | string | { text: string; position: SubTextPosition; } | undefined | Additional descriptive text for the input | |||
validators | RegisterOptions | undefined | validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider. | |||
visibleFrom | Breakpoint | undefined | When defined, the component is hidden until the screen width reaches the specified breakpoint. |
Toggle Classes
| Class Name | Description |
|---|---|
| .abyss-toggle-container | Toggle container for the visual elements |
| .abyss-toggle-descriptors | Toggle descriptors root element |
| .abyss-toggle-input | Toggle input element |
| .abyss-toggle-label | Toggle label element |
| .abyss-toggle-main-container | Toggle main container element |
| .abyss-toggle-root | Toggle root element |
| .abyss-toggle-sub-text | Toggle sub text element |
| .abyss-toggle-thumb | Toggle thumb indicator |
| .abyss-toggle-thumb-icon | The icon inside the thumb |
Adheres to the Switch WAI-ARIA design patternopens in a new window.
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
Click on the token row to copy the token to your clipboard.
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 |
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.color.cursor | #196ECF | |
| 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
| 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 |