# Core/Switch - Design

## Properties

### Label

Switches must be paired with an accessible label, using text that clearly describes the action being performed in 1
to 3 words. The language of the label should be phrased in a way that a response of “on”/“off” or “yes”/”no” makes
sense to the user.

<img src="images/guidelines/switch/example-1.png" />

### Size

Switches come in two different sizes. Medium is the default and preferred size for most situations. Small size is
used when a switch is inline with another element, such as a table or popover.

<img src="images/guidelines/switch/example-2.png" />

### Selected

Switches appear as either selected (on) or unselected (off). Switches cannot be in an indefinite state.

<img src="images/guidelines/switch/example-3.png" />

### Disabled

Switches can be disabled in either a selected or unselected state if there is a prerequisite to altering its state.

<img src="images/guidelines/switch/example-4.png" />

## Behavior

### Immediate

Switches immediately update the state of the application or UI when their state changes. If a delay is necessary, a
loading indicator should be used to inform the user that the process is taking longer.

<img src="images/guidelines/switch/example-5.png" />

### Labels

Avoid using the words “on” or “off” within the label. Switches imply an on/off state so including it in the label is
redundant.

<img src="images/guidelines/switch/example-6.png" />

## Best Practices

### Labels

**Do**

<img src="images/guidelines/switch/example-7.png" />

Do use clear and concise labels.

**Don't**

<img src="images/guidelines/switch/example-8.png" />

Avoid using action-related verbs with “on” or “off” when adding labels to controls. Switches imply an on/off state
so including it in the label is redundant.

### Placement

**Do**

<img src="images/guidelines/switch/example-9.png" />

Do use switches as trailing elements.

**Don't**

<img src="images/guidelines/switch/example-10.png" />

Don’t use switches as leading elements.

**Do**

<img src="images/guidelines/switch/example-11.png" />

Do ensure switches are either aligned with the grid or with each other when multiple switches are stacked.

**Don't**

<img src="images/guidelines/switch/example-12.png" />

Don't misalign switches by placing them immediately after labels when multiple switches are stacked, as this can
affect legibility.

### Checkbox vs Switch

**Do**

<img src="images/guidelines/switch/example-13.png" />

If the action is part of a larger form, use a checkbox instead. The items will be submitted with the rest of the
form details.

**Don't**

<img src="images/guidelines/switch/example-14.png" />

Switches apply changes immediately and don't require the user to submit anything. If you need to include the data in
form content, use a checkbox set.

### Radio vs Switch

**Do**

<img src="images/guidelines/switch/example-15.png" />

Switches are used for activation, not selection. If you are selecting between two available options, use a radio set
instead.

**Don't**

<img src="images/guidelines/switch/example-16.png" />

Switches should not be used to choose between opposing or discrete options. Instead, use switches for on/off
situations.

## Accessibility

### Keyboard interaction

| Key                    | Function                                                      |
| ---------------------- | ------------------------------------------------------------- |
| `Tab`<br />`Shift-Tab` | Moves focus into/out of the switch.                           |
| `Space`                | When focus is on the switch, changes the state of the switch. |

### WAI-ARIA Roles, States, and Properties

* The switch has `role=switch`.
* The switch has an accessible label provided by one of the following:
  * Visible text content contained within the element with `role=switch`.
  * A visible label referenced by the value of `aria-labelledby` set on the element with `role=switch`.
  * `aria-label` set on the element with `role=switch`.
* When on, the switch element has state `aria-checked` set to true.
* When off, the switch element has state `aria-checked` set to false.
* If a set of switches is presented as a logical group with a visible label, either:
  * The switches are included in an element with `role=group` that has the property `aria-labelledby` set to the ID of the element containing the group label.
  * The set is contained in an HTML `<fieldset>` and the label for the set is contained in an HTML `<legend>` element.
* If the presentation includes additional descriptive static text relevant to a switch or switch group, the switch or switch group has the property `aria-describedby` set to the ID of the element containing the description.