Skip to Content
Workday Design
Design SystemBrand Resources
CTRL K

Switch

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

Interaction Modes

Configuring

Reviewing

Selecting

Sources

Github

Storybook

Install

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

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.1.7

Experience Surfaces

Page Body Inline

Component Type

Input

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.1.7

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.
Switch (Main) Documentation

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 isRequired>
      <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” .

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

Accessibility Guidelines

Keyboard Interaction

Each Switch must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Checkboxes must support the following keyboard interactions:

  • Tab: focus a Switch
  • Space: change the state of a focused switch

Screen Reader Interaction

Switch must communicate the following to users:

  • The accessible name (label) of the focused Switch
  • The state of the Switch

Design Annotations Needed

No design annotations needed for Switch

Implementation Markup Needed

  • Switch must have a required attribute when the Switch is required for submission.
  • Switch must have an aria-invalid=”true” attribute when it has an error condition
  • [Included in component] Switch is based on an HTML Checkbox Input, which already supports the “on” and “off” states of this component without the aria-checked property.
  • [Included in component] Switch must have an ARIA role=“switch” attribute augmenting the checkbox input element.
  • [Included in component] A <label> element is required with a for attribute referencing the unique id value of the associated Switch.
  • [Included in component] A disabled attribute is set when the Switch is disabled.

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.