Switch
Switch is a selection control used to toggle a function on or off.
Component Type
Input
Platform
Web
Component
Sana Canvas
Delivery Channels
Web
Version
16.2.12Experience Surfaces
Page Body Inline
Switch (Preview) vs. Switch (Main)
@workday/canvas-kit-preview-react) documented here on this page. The Switch in the Main package (@workday/canvas-kit-react) will eventually be replaced with the Switch in the Preview package. See the Packages Glossary for what Preview means.Anatomy

- Form Label: Identifies the input. Positions above or left of the Switch.
- Switch: Interactive control that toggles between on and off states.
- Hint Text (Optional): Supplemental text below the Switch for additional context or guidance.
- Thumb Icon: Icon inside the thumb that reinforces the current state; ✔︎ for on, ✕ for off.
- Switch Label (Optional): Inline text adjacent to the Switch that reflects the active state (e.g., “On” / “Off”).
Usage Guidance
- Use a Switch to enable or disable a mode, feature, or function.
- Switches take effect immediately and no confirmation step required.
- A Switch only has two states: on and off.
- The Form Label can be positioned above or to the left of the Switch for LTR languages, and above or to the right for RTL languages.
- The Switch Label is aligned to the right of the Switch for LTR languages, and to the left for RTL languages.
When to Use
- Use to turn a mode on or off.
When to Use Something Else
- Consider using Radio Buttons if users need to select one item from a list of options.
- Consider using a Checkbox if users need to confirm a statement such as an agreement.
- Consider using a Checkbox or Multi-select Prompt if users can select multiple items from a list of options.
Examples
Basic Example
Switch should be used in tandem with Form Field to meet accessibility standards.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<FormField>
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} checked={checked} onChange={handleChange} />
</FormField.Field>
</FormField>
);
};
Disabled
Set the disabled prop of the Switch to prevent users from interacting with it.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<FormField>
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input disabled as={Switch} checked={checked} onChange={handleChange} />
</FormField.Field>
</FormField>
);
};
Ref Forwarding
Switch supports ref forwarding . It will forward
ref to its underlying <input type="checkbox"> element.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const ref = React.useRef(null);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
const handleClick = () => {
ref.current.focus();
};
return (
<>
<FormField>
<FormField.Label>Dark Mode</FormField.Label>
<FormField>
<FormField.Input as={Switch} checked={checked} ref={ref} onChange={handleChange} />
</FormField>
</FormField>
<PrimaryButton onClick={handleClick}>Focus Switch</PrimaryButton>
</>
);
};
Label Position Horizontal
Set the orientation prop of the Form Field to designate the position of the label relative to the
input component. By default, the orientation will be set to vertical.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<FormField orientation="horizontalStart">
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} checked={checked} onChange={handleChange} />
</FormField.Field>
</FormField>
);
};
Error States
Set the error prop of the wrapping Form Field to "caution" or "error" to set the Switch to the
Caution or Error state, respectively. You will also need to use <FormField.Hint/> for hint or
error text to meet accessibility standards.
The error prop may be applied directly to the Switch with a value of Switch.ErrorType.Caution or
Switch.ErrorType.Error if Form Field is not being used.
Caution
We were unable to activate Dark Mode.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<FormField error="caution">
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} checked={checked} onChange={handleChange} />
<FormField.Hint>We were unable to activate Dark Mode.</FormField.Hint>
</FormField.Field>
</FormField>
);
};
Error
We were unable to activate Dark Mode.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<FormField error="error">
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} checked={checked} onChange={handleChange} />
<FormField.Hint>We were unable to activate Dark Mode.</FormField.Hint>
</FormField.Field>
</FormField>
);
};
Right-to-Left (RTL)
Switch supports right-to-left languages when specified in the CanvasProvider theme.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {CanvasProvider} from '@workday/canvas-kit-react/common';
import {FormField} from '@workday/canvas-kit-react/form-field';
export default () => {
const [checked, setChecked] = React.useState(false);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setChecked(event.target.checked);
};
return (
<CanvasProvider dir="rtl">
<FormField isRequired>
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} checked={checked} onChange={handleChange} />
</FormField.Field>
</FormField>
</CanvasProvider>
);
};
Custom Styles
Switch supports custom styling via the cs prop. For more information, check our
“How To Customize Styles” .
Accessibility
The primary accessibility goal is a visible, programmatically determinable name and an on or off
state that assistive technology can expose. Use Switch for a single setting that takes effect
immediately when toggled (for example, “Dark Mode”). When the user selects one or more options that
are applied on form submission, use Checkbox instead. Switch
does not render its own <label>, so it relies on FormField for its name, hint, error, and
required wiring — see FormField’s accessibility documentation.
Minimum Accessible Structure
The following matches the Basic Example. Every Switch needs FormField, a
visible FormField.Label, and FormField.Input as={Switch} inside FormField.Field.
import React from 'react';
import {Switch} from '@workday/canvas-kit-preview-react/switch';
import {FormField} from '@workday/canvas-kit-react/form-field';
const Example = () => {
return (
<FormField>
<FormField.Label>Dark Mode</FormField.Label>
<FormField.Field>
<FormField.Input as={Switch} />
</FormField.Field>
</FormField>
);
};Built-in Behaviors
Canvas Kit applies these automatically when you compose Switch with FormField
subcomponents. Do not duplicate them in consuming code.
ARIA and DOM (applied by Switch and FormField):
Switch: Renders a native<input type="checkbox">withrole="switch". The nativecheckedstate is exposed to assistive technology as on or off, so noaria-checkedis needed. Canvas Kit assigns anidwithuseUniqueIdunless you passid.- Track, thumb, and check/x icon: Purely visual. The icon is a Canvas Kit
SystemIcon, whose SVG markup setsrole="presentation"andfocusable="false", so it is not announced. disabled: Maps to the nativedisabledattribute.
Keyboard (native checkbox behavior):
Switch uses native <input type="checkbox"> keyboard behavior (tab order and Space to
toggle). Do not intercept Space or otherwise prevent the native toggle.
Screen reader expectations (when built-in behaviors are used as intended):
- On focus, assistive technology announces the
FormField.Labeltext, the “switch” role, and the on or off state; when applicable, required state, invalid state (error="error"), andFormField.Hinttext viaaria-describedby - Toggling announces the new on or off state
- The Caution state is visual only —
aria-invalidis not set forerror="caution" - Disabled switches are skipped in the tab order and may be announced as unavailable
For label, hint, and error association details, see FormField’s Built-in Behaviors.
Accessibility Requirements
Required in application code for an accessible Switch. Rows marked (conditional) apply only when the situation matches—otherwise omit.
If no design spec is provided: use a visible FormField.Label, wrap the control with
FormField.Input as={Switch} inside FormField.Field, and control it with checked and
onChange. Omit isRequired, error, FormField.Hint, disabled,
isHidden, a custom id, and a ref unless the spec requires them.
Programmatic focus (conditional — omit by default):
Attach a ref only when the product must move focus to the Switch after an action. Do not attach a
ref or call focus() unless the design or developer asks for it. See
Ref Forwarding under Usage for a complete Storybook example.
| Requirement | How to satisfy |
|---|---|
| Accessible name | Visible, non-empty FormField.Label describing the setting (for example, “Dark Mode”), not the state (“On”/“Off”). Use FormField.Label isHidden only when an equally clear visible alternative exists |
| Input wiring | FormField.Input as={Switch} inside FormField.Field. See FormField accessibility for label, hint, error, and required wiring |
| Required state (conditional) | isRequired on FormField only when the form cannot be submitted unless the Switch is on — native required on a checkbox means it must be checked |
| Disabled (conditional) | disabled on FormField.Input when the spec marks the setting unavailable. See Disabled |
| Programmatic focus (conditional) | ref on FormField.Input and call focus() when the product requires it — omit by default (see Programmatic focus above and Ref Forwarding) |
Summary for code generation:
- REQUIRED:
FormField+ visibleFormField.Label+FormField.Input as={Switch}insideFormField.Field - CONDITIONAL:
isRequiredonly when the Switch must be on;disabled; programmatic focus viaref. See FormField accessibility for shared FormField conditionals (hint, error, and caution).
Anti-Patterns
Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):
- Render Switch without
FormFieldandFormField.Label— Switch has no built-in label. For shared FormField anti-patterns (manual ARIA wiring, color-only errors, broken ID references), see FormField Anti-Patterns - Manually set
role,aria-checked,aria-labelledby,aria-describedby,aria-invalid, oridon Switch — Canvas Kit wires these from the native checkbox andFormField - Nest
FormFieldinsideFormFieldinstead of usingFormField.Field— the innerFormFieldbreaks the label association - Put the state in the label (for example, “Dark Mode: On”) or add a visually hidden “on”/“off”
string — the state is already announced from
role="switch"andchecked - Set
errordirectly on Switch insideFormField— set it onFormFieldsoaria-invalidand the visual ring stay in sync. Settingerroron a Switch outsideFormFieldis visual only and does not setaria-invalid - Use
isRequiredfor a setting that can validly be off - Use Switch for selections that only apply on form submission, or for multiple related options — use Checkbox instead
- Use
aria-disabledinstead ofdisabled— Switch maps unavailability to the nativedisabledattribute
Component API
Switch
Props
Props extend from input. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
checked | boolean | If true, set the Switch to the on state. | false |
disabled | boolean | If true, set the Switch to the disabled state. | false |
id | string | The HTML | |
onChange | (e: <>) => void | The function called when the Switch state changes. | |
value | string | The value of the Switch. | |
error | | The type of error associated with the Switch (if applicable). | |
children | React.ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref<R = input> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
Switch.ErrorType
Basic type information:
ErrorTypeContent Guidelines
- Switch Labels are written in title case.
- Use labels such as “on” and “off” or “enable” and “disable” to communicate the state of the Switch.