Switch

Switch is a selection control that is used to switch between two potential states.

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

Anatomy

Image of a Switch Input in its on state.

  1. Switch Label: Title of the input. Label position could be set to the top or left of the Switch Input.
  2. Switch: The element that when clicked, switches between two states.

Usage Guidance

  • A Switch is used to enable or disable a mode, feature, or function.
  • Switches have an immediate effect on the system.
  • Switches only have 2 options: on or off.
  • The Switch Label can be positioned in two places; above or left of the Switch for LTR languages. Switch Labels are aligned to the right of the Switch for RTL languages.

When to Use

  • Use to turn an option 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.

Disabled

Set the disabled prop of the Switch to prevent users from interacting with it.

Ref Forwarding

Switch supports ref forwarding. It will forward ref to its underlying <input type="checkbox"> element.

Label Position

Set the labelPosition prop of the wrapping Form Field to designate the position of the label relative to the Switch. labelPosition accepts the following values:

  • FormField.LabelPosition.Top (Default)
  • FormField.LabelPosition.Left

Error States

Set the error prop of the wrapping Form Field to FormField.ErrorType.Alert or FormField.ErrorType.Error to set the Switch to the Alert or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards.

The error prop may be applied directly to the Switch with a value of Switch.ErrorType.Alert or Switch.ErrorType.Error if Form Field is not being used.

Alert

Alert: We were unable to activate Dark Mode.

Error

Error: We were unable to activate Dark Mode.

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

theme
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

Specifications

GivenWhenThen
given the 'Basic' story is rendered
    • it should not have any axe errors
    given the 'Basic' story is rendered
    • clicked
    • it should be checked
    given the 'Alert' story is rendered
      • it should not have any axe errors
      given the 'Alert' story is rendered
      • clicked
      • it should be checked
      given the 'Error' story is rendered
        • it should not have any axe errors
        given the 'Error' story is rendered
        • clicked
        • it should be checked
        given the 'Disabled' story is rendered
          • it should not have any axe errors
          given the 'Disabled' story is rendered
            • it should be disabled
            Source: Switch.spec.ts

            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.

            Can't Find What You Need?

            Check out our FAQ section which may help you find the information you're looking for.

            FAQ Section