Switch

Use a Switch to adjust settings or make a binary selection like on or off and true or false.

Deciding whether to use a Switch vs. other selection controls can be confusing. The table below summarizes questions and answers about these frequently used elements.

A Switch displays a state through different methods and locations.

• The Switch status message indicates if the Switch is on or off
• The form status message indicates what the Switch turns on or off
• The check icon is used in place of the Switch status message if space is limited
• The Switch status message is used with a check icon to add clarity if necessary

Adding a custom status message is not a requirement. By default, switches already indicate their state both graphically and to assistive tech (e.g., announcing “on” and “off” to screen readers when receiving focus or being toggled).

If you would like to add a status message, you can do so via following method:

1. Add a <div> with an id value within <rh-switch>.
2. Within the <div>, add two <span> elements—one for each state of the switch.
3. For the “on” <span>, add a data-state="on" attribute and add your desired status text within the <span>.
4. For the “off” <span>, add a data-state="off" attribute and add your desired status text within the <span>.
5. Add an aria-describedby attribute to <rh-switch> pointing to the status <div>’s id.

Here's an example of a status message from a Switch demo:

• If you are not adding a custom status message <div>, do not include an aria-describedby attribute, as it will have no id to which it can point.
• You can also add static messages by placing text directly in the status <div>, rather than within the dynamic “on” and “off” <span> elements.
• You may need to style the status <div> to place it where you want in relation to the switch.

Unlike a status message, a form label is required whenever Switch is used. A form label describes a Switch's purpose. There is no slot for a form label within the web component and has to be added separately.

In general, users scan and do not read everything, so use keywords and avoid long phrases and questions.

The status message and form label should be short and direct, not neutral or ambiguous.

Ensure the message is clear when a Switch is toggled to the On or Off position and that the form label explains the switch's purpose.

Do not use a status message that does not make the switch state clear, especially if the form label is hidden.

The recommended maximum character count is listed below and includes spaces.

Use a stack of Switches for situations where multiple independent options need to be turned on or off.

A Switch is successfully toggled when the handle slides to the other side of the track and the status message changes. When a user toggles a Switch, the effects should start immediately without needing to save. If immediate results are not achievable, another element should be used instead (see table above in Usage section).

To avoid confusion as to what a Switch will do, always include some kind of status message or a form label.

Ensure the message is clear when a Switch is toggled to the On or Off position and that the form label explains the switch's purpose.

Do not make it unknown to users what a Switch will do when toggled.

A Switch controls binary options, not opposing ones. A binary option represents a single selection that is either on or off.

Switches can be used in a list to toggle multiple independent options.

Use Switches in a list only if the effects from toggling each Switch are immediate.

Do not use Switches in a list if a user has to save to see the effects