Switch

Anatomy

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.

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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 {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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 {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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 {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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 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.Caution or Switch.ErrorType.Error if Form Field is not being used.

Caution

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {Switch} from '@workday/canvas-kit-react/switch';

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>
  );
};

Custom Styles

Switch supports custom styling via the cs prop. For more information, check our “How To Customize Styles”.

Component API

ErrorType

Specifications

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.

Anatomy

1. Container: Interactive area that the handle moves across.
2. Handle: Affordance for the toggle direction.

Usage Guidance

When to Use

• Use a Switch to enable users to toggle functions on and off that are applied immediately without the need for any further validation (e.g., in Settings).

When to Consider Something Else

• Consider using alternative selection controls such as a Radio Button for selecting a singular item or a Checkbox for multiple items. These selection controls are lost without saving.

Behaviors

A function has successfully been altered when the handle moves across the container, changing the underlying status.

Notification States

Because a Switch can alter functionality, a Switch supports both warning and error states.

API Guidelines

Methods

Class name: Switch Module name: UIComponentsPlugin

public init(
 	featureData: FeatureMetricsData,
 	isOn: Binding<Bool>,
 	state: State,
	localizer: LocalizationAdapting
)

Parameters

Accessibility Guidelines

• The Switch component must have an AccessibilityLabel that matches the visible label displayed with the switch.
• The Switch component and its visible label must be grouped as one focus stop for assistive technologies.
• When an error or alert is displayed, the error/alert text must be included in the AccessibilityValue of the Switch component.

Content Guidelines

Coming soon…

Anatomy

1. Container: Interactive area that the handle moves across.
2. Handle: Affordance for the toggle direction.

Usage Guidance

When to Use

• Use a Switch to enable users to toggle functions on and off that are applied immediately without the need for any further validation (e.g., in Settings).

When to Consider Something Else

• Consider using alternative selection controls such as a Radio Button for selecting a singular item or a Checkbox for multiple items. These selection controls are lost without saving.

Behaviors

A function has successfully been altered when the handle moves across the container, changing the underlying status.

Notification States

Because a Switch can alter functionality, a Switch supports both warning and error states.

Pressed State

When pressing on a Switch, the handle enlarges to fill more of the container.

API Guidelines

Component Definition

@Composable
fun SwitchUiComponent(
    modifier: Modifier = Modifier,
    checked: Boolean,
    showIcon: Boolean = false,
    semanticState: SemanticState = SemanticState(),
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    onCheckedChange: ((Boolean) -> Unit) = {},
) {

Parameters

Accessibility Guidelines

Coming soon…

Content Guidelines

Coming soon…