Skip to Content

Switch

Switch is a selection control used to toggle a function on or off.

Interaction Modes

Configuring

Reviewing

Selecting

Install

yarn add @workday/canvas-kit-preview-react

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

Switch (Preview) vs. Switch (Main)

We recommend you use the Switch in the Preview package (@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

Image of a Switch Input in its on state.
  1. Form Label: Identifies the input. Positions above or left of the Switch.
  2. Switch: Interactive control that toggles between on and off states.
  3. Hint Text (Optional): Supplemental text below the Switch for additional context or guidance.
  4. Thumb Icon: Icon inside the thumb that reinforces the current state; ✔︎ for on, ✕ for off.
  5. 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"> with role="switch". The native checked state is exposed to assistive technology as on or off, so no aria-checked is needed. Canvas Kit assigns an id with useUniqueId unless you pass id.
  • Track, thumb, and check/x icon: Purely visual. The icon is a Canvas Kit SystemIcon, whose SVG markup sets role="presentation" and focusable="false", so it is not announced.
  • disabled: Maps to the native disabled attribute.

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.Label text, the “switch” role, and the on or off state; when applicable, required state, invalid state (error="error"), and FormField.Hint text via aria-describedby
  • Toggling announces the new on or off state
  • The Caution state is visual only — aria-invalid is not set for error="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.

RequirementHow to satisfy
Accessible nameVisible, 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 wiringFormField.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 + visible FormField.Label + FormField.Input as={Switch} inside FormField.Field
  • CONDITIONAL: isRequired only when the Switch must be on; disabled; programmatic focus via ref. 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 FormField and FormField.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, or id on Switch — Canvas Kit wires these from the native checkbox and FormField
  • Nest FormField inside FormField instead of using FormField.Field — the inner FormField breaks 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" and checked
  • Set error directly on Switch inside FormField — set it on FormField so aria-invalid and the visual ring stay in sync. Setting error on a Switch outside FormField is visual only and does not set aria-invalid
  • Use isRequired for 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-disabled instead of disabled — Switch maps unavailability to the native disabled attribute

Component API

Switch

Props

Props extend from input. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
checkedboolean

If true, set the Switch to the on state.

false
disabledboolean

If true, set the Switch to the disabled state.

false
idstring

The HTML id of the underlying checkbox input element.

onChange(e: <>) => void

The function called when the Switch state changes.

valuestring

The value of the Switch.

error

The type of error associated with the Switch (if applicable).

childrenReact.ReactNode
asReact.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 React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

input
refReact.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 as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

Switch.ErrorType

Basic type information:

ErrorType

Content 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.