Switch

Overview Style Guidelines Code Demos Accessibility

Usage

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

Switch vs. other selection controls

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.

Question	Radio button	Single checkbox	Multiple checkboxes	Switch
How many options are available?	Multiple	1	Multiple	1
How many selections can a user make?	1	2 (on/off)	0 - all	2 (on/off)
Is there a default option?	Yes	Yes	No	Yes
How would you describe the choices?	Mutually exclusive	Mutually exclusive	Independent of each other	Mutually exclusive
When does the selection take effect?	After a user selects a submit button	After a user selects a submit button	After a user selects a submit button	Immediately

Variants

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:

Add a <div> with an id value within <rh-switch>.
Within the <div>, add two <span> elements—one for each state of the switch.
For the “on” <span>, add a data-state="on" attribute and add your desired status text within the <span>.
For the “off” <span>, add a data-state="off" attribute and add your desired status text within the <span>.
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:

Implementation notes:

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.

Status messages vs. form labels

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.

Learn how to use form labels with Switch

Writing content

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

Clarity of language

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.

Character count

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

Element	Character count
Switch status message	20
Form label	30

Layout

Stacking

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

four switches, half of which are on, stacked in a column

Behavior

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