Switch

A Switch is an interactive binary control. It should be used in forms when an "on/off" or "yes/no" input is needed.

Use Switch when the interaction result is immediate. Users shouldn't need to perform an additional action (like use a "Save" or "Submit" button) to confirm Switch input. For example, when a user turns on a "Receive notifications" Switch, they should start receiving notifications immediately upon performing the action.

Use a Checkbox to present a user with a single binary choice that is part of a form or otherwise requires a user to take an additional action to confirm input.

• SwitchGroup must have a legend that describes the collection.
• Switch always has the role="switch" attribute.
• Switch must have a visible label that is in close proximity to the control.
• If you want to mark a Switch as required, use the required prop.
  • Only use the required prop on the SwitchGroup if you want to mark the entire group as required.
  • If you want to mark a single Switch as required, use the required prop on it directly.
  • Ensure the label text includes wording that successfully describes the requirement to the user that they should toggle the Switch on
• When in an error state display an inline error message below the offending Switch that clearly describes the error.
• When displaying additional content based on toggling a Switch, be sure that the new content appears after the Switch in question so that it is naturally discoverable by assistive technology users.

The Switch can either be controlled, meaning there is an external state that determines if the Switch is on or not, or uncontrolled, meaning the Switch manages its own state.

To make an uncontrolled Switch, you do not pass the checked or onChange prop.

To make a controlled Switch, you must pass the checked and onChange prop.

A Switch is always displayed with a visible label. The label text should never change based on the state of the Switch.

In cases where the Switch requires additional context, you can display this information as help text below the Switch and label. This can help keep Switch labels concise. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component.

When a Switch is required to be 'on', a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user.

Use a disabled Switch to indicate to users that it is not interactive. If interactivity is dependent on another action, make that clear using help text.

Multiple Switches and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any Switch or other content.

To internationalize a Switch, simply pass different text to the Switch and SwitchGroup. The only exception to this is the required dot in the legend of a required SwitchGroup. To change the required dot's text, use the i18nRequiredLabel prop.

The default Switch state is off.

Use the disabled on Switch to indicate to users that it is not interactive and cannot be turned off. If interactivity is dependent on another action, make that clear using help text.

Switch label text should indicate what the Switch does when it is on, but should not describe the state itself ("enabled", "disabled"). Label text shouldn't change when the state of the Switch changes.

Switch labels should be concise and put the most important information in the first few words. Avoid making the label a question.

Use Help Text for additional information, like any notable implications of turning on the Switch.