Skip to content

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

Specification of ToggleSwitch.

  1. 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.
  2. 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.
  3. 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:

States of the ToggleSwitch component for both off and on states: default, hover, active, focus, and disabled.

  1. Default off
  2. Hover off
  3. Active off
  4. Focus off
  5. Disabled off
  6. Default on
  7. Hover on
  8. Active on
  9. Focus on
  10. 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

ToggleSwitch group including different text formats and a link.

Do:
  • 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.

ToggleSwitch group with bolded labels and a link within the last label.

Don't:
  • Bold all the label.
  • Link the entire ToggleSwitch label as it could cause issues with the selection.

Orientation

Two ToggleSwitches stacked vertically.

Do:
  • Use ToggleSwitch groups in a vertical orientation for a clear and organized layout.

ToggleSwitch conveying switching between two opposing options.

Don't:
  • Use a ToggleSwitch to control opposing options.

References

  1. Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)

Keyboard navigation

KeyFunction
TabIt 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 + TabIt 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 / SpaceIf the focus is placed on the ToggleSwitch, it toggles the switch on and off.

Demos

Configurable

NameValue
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

Turn on to use the visual editor. You can switch back to source mode at any time.

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.

Use the toggle switch to show hidden content.

Here is the hidden content

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.

Editing options General option for editing
Visit Special:Preferences for more editing options.

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:

  1. Wrap the group in an element with role="group"
  2. 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 nameDescriptionTypeDefault
modelValueCurrent value of the toggle switch or toggle switch group.

Provided by v-model binding in the parent component.
boolean|string[]|number[]false
inputValueHTML "value" attribute to assign to the input element.

Required for groups of ToggleSwitches. Can be omitted for single true/false switches.
string|number|booleanfalse
alignSwitchWhether to align the switch to the end of the container.

Useful for ToggleSwitch groups, where each switch should be aligned regardless of label length.
booleanfalse
hideLabelWhether the label should be visually hidden.

Note that this will also hide the description.
booleanfalse
disabledWhether the disabled attribute should be added to the input.booleanfalse

Events

Event namePropertiesDescription
update:modelValuemodelValue boolean - The new model valueEmitted when modelValue changes.

Slots

NameDescriptionBindings
defaultLabel text.
descriptionShort 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 class cdx-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
Turn on to use the visual editor. You can switch back to source mode at any time.

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.