ToggleSwitch ​
A ToggleSwitch enables the user to instantly toggle between on and off states.
Guidelines ​
When to use toggle switches ​
Toggle switches must feature a descriptive label.
Use the ToggleSwitch component only where an instant change in the user-interface based on their assigned action is intended. For non-instant selections and selection groups, use Checkbox instead.
Specifications ​
- Toggle switch label
The toggle switch must always contain a label, with the text size matching the base font size for consistency with the body text. The label should be short, with text that clearly describes the state being toggled. - Toggle switch
Toggle switches make the on and off states visually distinct by using different colors and moving the grabber from left to right and vice versa. - Description (optional)
If additional information about the label is required, a description can be included.
Component limitations ​
The ToggleSwitch label will expand to fit longer text while the ToggleSwith itself remains aligned with the first line of the label's text.
A group of toggle switches should consist of at least 2 items, with no maximum limit on the number of toggle switches per group.
Refer to the ToggleSwitch component in Codex Figma.
Interaction states ​
Toggle switches’ states were designed with accessible color variations. These, in addition to the toggle handle, facilitate distinguishing the toggle switch’s on or off states (e.g. disabled, hover, active) visually:
- Default off
- Hover off
- Active off
- Focus off
- Disabled off
- Default on
- Hover on
- Active on
- Focus on
- Disabled on
Accessibility note
The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”. [1]
Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).
Best practices ​
Consider the following recommendations when using toggle switches.
Label’s format ​
- Accompany the ToggleSwitch with a label that matches the base font size.
- Use text formatting and links in the label.
- Include a description below the label to provide additional information.
- Bold all the label.
- Link the entire ToggleSwitch label as it could cause issues with the selection.
Orientation ​
- Use ToggleSwitch groups in a vertical orientation for a clear and organized layout.
- Use a ToggleSwitch to control opposing options.
References ​
Keyboard navigation ​
Key | Function |
---|---|
Tab | It moves the focus to the next ToggleSwitch within a group or to the next interactive element in tab order when the focus is placed on the last ToggleSwitch of a group. |
Shift + Tab | It moves the focus to the previous button within the group or to the previous interactive element when the focus is placed on the first button of the group. |
Enter / Space | If the focus is placed on the ToggleSwitch, it toggles the switch on and off. |
Demos ​
Configurable ​
Name | Value |
---|---|
Props | |
alignSwitch | |
hideLabel | |
disabled | |
Slots | |
default | |
View | |
Reading direction |
Single switch with label and description ​
Always include label text via the default slot. You can also add description text via the #description
slot.
A single switch does not need an inputValue
prop. v-model
is bound to a boolean value: true
for "on", false
for "off".
Toggle switch value: false
In rare cases, a visible label is not necessary. You can use the hideLabel
prop to visually hide the label, which will still appear in the markup for accessibility purposes.
Form field ​
When used in a form, a single ToggleSwitch or group of ToggleSwitches can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
When building a ToggleSwitch field, always set isFieldset
to true
, even for a single ToggleSwitch, to ensure proper accessibility support. This wraps the group in a <fieldset>
element and labels it with an associated <legend>
.
If using a ToggleSwitch or ToggleSwitch group outside of a form, follow the instructions in the next demo.
ToggleSwitch group ​
For a group of related toggle switches, each ToggleSwitch component's v-model
will be bound to an array of the inputValue
props of the toggle switches that are currently "on".
Use the alignSwitch
prop to align all of the switches to the end of the container, creating a more streamlined look.
This demo shows what to do when using a ToggleSwitch group outside of a form:
- Wrap the group in an element with
role="group"
- Connect the group with a label via the
aria-labelledby
attribute
ToggleSwitch group value: [ "switch-1" ]
Vue usage ​
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input>
element within the component.
For a single toggle switch, the v-model
value will be a boolean true
when the switch is "on" and false
when "off".
For multiple toggle switches, the v-model
value will be an array of the inputValue
props of any currently "on" switches (or an empty array if all switches are "off").
Props ​
Prop name | Description | Type | Default |
---|---|---|---|
modelValue | Current value of the toggle switch or toggle switch group. Provided by v-model binding in the parent component. | boolean|string[]|number[] | false |
inputValue | HTML "value" attribute to assign to the input element. Required for groups of ToggleSwitches. Can be omitted for single true/false switches. | string|number|boolean | false |
alignSwitch | Whether to align the switch to the end of the container. Useful for ToggleSwitch groups, where each switch should be aligned regardless of label length. | boolean | false |
hideLabel | Whether the label should be visually hidden. Note that this will also hide the description. | boolean | false |
disabled | Whether the disabled attribute should be added to the input. | boolean | false |
Events ​
Event name | Properties | Description |
---|---|---|
update:modelValue | modelValue boolean - The new model value | Emitted when modelValue changes. |
Slots ​
Name | Description | Bindings |
---|---|---|
default | Label text. | |
description | Short description text. |
CSS-only version ​
Markup structure ​
With description ​
To add a description below the label:
- Add a
<span>
after the<label>
element with an ID and classcdx-label__description
. Include the description text here. - Add an
aria-describedby
attribute to the<input>
element with the value of the ID of the description
With visually-hidden label ​
For a visually-hidden label, add the cdx-label--visually-hidden
class to the <div>
that has the cdx-label
class.
Initially on ​
The toggle switch appears "on" when the hidden checkbox is checked. To initially set the switch to "on", add the checked
attribute to the <input>
.
Disabled ​
To disable the toggle switch, add the disabled
attribute to the <input>
element.