ToggleSwitch

A toggle switch enables the user to instantly toggle between on and off states.

Guidelines

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

Example of a group of Codex ToggleSwitches with one on and one off.

Specifications

Specification of Toggle Switch.

Toggle switch label
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.

Refer to the Toggle Switch 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 Toggle Switch component for both off and on states: default, hover, active, focus, and disabled.

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

References

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

Demos

Configurable

Label for ToggleSwitch

Name	Value
Props
alignSwitch
hideLabel
disabled
Slots
default
View
Reading direction	Left to right (LTR) Right to left (RTL)

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

Visual editing mode 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.

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

Enable section editing by right clicking on section titles

Edit pages on double click

Enable showing appreciation for other users with the WikiLove tab

Visit Special:Preferences for more editing options.

NPMMediaWiki

vue

<template>
	<cdx-field :is-fieldset="true">
		<cdx-toggle-switch
			v-for="toggleSwitch in toggleSwitches"
			:key="'switch-' + toggleSwitch.value"
			v-model="fieldValue"
			:input-value="toggleSwitch.value"
			:align-switch="true"
		>
			{{ toggleSwitch.label }}
		</cdx-toggle-switch>
		<template #label>
			Editing options
		</template>
		<template #description>
			General option for editing
		</template>
		<template #help-text>
			Visit Special:Preferences for more editing options.
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxToggleSwitch, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'SwitchGroupField',
	components: { CdxToggleSwitch, CdxField },
	setup() {
		const fieldValue = ref( [ 'wikilove' ] );
		const toggleSwitches = [
			{
				label: 'Enable section editing by right clicking on section titles',
				value: 'rightClickTitle'
			},
			{
				label: 'Edit pages on double click',
				value: 'doubleClick'
			},
			{
				label: 'Enable showing appreciation for other users with the WikiLove tab',
				value: 'wikilove'
			}
		];

		return {
			fieldValue,
			toggleSwitches
		};
	}
} );
</script>

vue

<template>
	<cdx-field :is-fieldset="true">
		<cdx-toggle-switch
			v-for="toggleSwitch in toggleSwitches"
			:key="'switch-' + toggleSwitch.value"
			v-model="fieldValue"
			:input-value="toggleSwitch.value"
			:align-switch="true"
		>
			{{ toggleSwitch.label }}
		</cdx-toggle-switch>
		<template #label>
			Editing options
		</template>
		<template #description>
			General option for editing
		</template>
		<template #help-text>
			Visit Special:Preferences for more editing options.
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxToggleSwitch, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'SwitchGroupField',
	components: { CdxToggleSwitch, CdxField },
	setup() {
		const fieldValue = ref( [ 'wikilove' ] );
		const toggleSwitches = [
			{
				label: 'Enable section editing by right clicking on section titles',
				value: 'rightClickTitle'
			},
			{
				label: 'Edit pages on double click',
				value: 'doubleClick'
			},
			{
				label: 'Enable showing appreciation for other users with the WikiLove tab',
				value: 'wikilove'
			}
		];

		return {
			fieldValue,
			toggleSwitches
		};
	}
} );
</script>

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" ]

ToggleSwitch group demo

Toggle switch 1

Toggle switch 2 with a longer label

Toggle switch 3

NPMMediaWiki

vue

<template>
	<div>
		<p class="cdx-docs-demo-text">
			ToggleSwitch group value: {{ toggleSwitchValue }}
		</p>

		<div role="group" aria-labelledby="cdx-demo-switch-group-label">
			<cdx-label id="cdx-demo-switch-group-label">
				ToggleSwitch group demo
			</cdx-label>

			<cdx-toggle-switch
				v-for="toggleSwitch in toggleSwitches"
				:key="'switch-' + toggleSwitch.value"
				v-model="toggleSwitchValue"
				:input-value="toggleSwitch.value"
				:align-switch="true"
			>
				{{ toggleSwitch.label }}
			</cdx-toggle-switch>
		</div>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxToggleSwitch, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'SwitchGroup',
	components: { CdxToggleSwitch, CdxLabel },
	setup() {
		const toggleSwitchValue = ref( [ 'switch-1' ] );
		const toggleSwitches = [
			{
				label: 'Toggle switch 1',
				value: 'switch-1'
			},
			{
				label: 'Toggle switch 2 with a longer label',
				value: 'switch-2'
			},
			{
				label: 'Toggle switch 3',
				value: 'switch-3'
			}
		];

		return {
			toggleSwitchValue,
			toggleSwitches
		};
	}
} );
</script>

vue

<template>
	<div>
		<p class="cdx-docs-demo-text">
			ToggleSwitch group value: {{ toggleSwitchValue }}
		</p>

		<div role="group" aria-labelledby="cdx-demo-switch-group-label">
			<cdx-label id="cdx-demo-switch-group-label">
				ToggleSwitch group demo
			</cdx-label>

			<cdx-toggle-switch
				v-for="toggleSwitch in toggleSwitches"
				:key="'switch-' + toggleSwitch.value"
				v-model="toggleSwitchValue"
				:input-value="toggleSwitch.value"
				:align-switch="true"
			>
				{{ toggleSwitch.label }}
			</cdx-toggle-switch>
		</div>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxToggleSwitch, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'SwitchGroup',
	components: { CdxToggleSwitch, CdxLabel },
	setup() {
		const toggleSwitchValue = ref( [ 'switch-1' ] );
		const toggleSwitches = [
			{
				label: 'Toggle switch 1',
				value: 'switch-1'
			},
			{
				label: 'Toggle switch 2 with a longer label',
				value: 'switch-2'
			},
			{
				label: 'Toggle switch 3',
				value: 'switch-3'
			}
		];

		return {
			toggleSwitchValue,
			toggleSwitches
		};
	}
} );
</script>

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

The structure below can be used for most cases. If you need a description or a visually-hidden label, see the sections on those features below.

Label

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 class cdx-label__label to the <label> element
Wrap the label and description in a div with classes cdx-toggle-switch__label and cdx-label
Add an aria-describedby attribute to the <input> element with the value of the ID of the description

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

For a visually-hidden label:

Add class cdx-label__label to the <label> element
Wrap the label in a div with classes cdx-toggle-switch__label, cdx-label, and cdx-label--visually-hidden

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

Initially on

Disabled

To disable the toggle switch, add the disabled attribute to the <input> element.

Disabled, off
Disabled, on

ToggleSwitch ​

Guidelines ​

Using toggle switches ​

Specifications ​

Interaction states ​

References ​

Demos ​

Configurable ​

Single switch with label and description ​

Form field ​

ToggleSwitch group ​

Vue usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

With description ​

With visually-hidden label ​

Initially on ​

Disabled ​

ToggleSwitch

Guidelines

Using toggle switches

Specifications

Interaction states

References

Demos

Configurable

Single switch with label and description

Form field

ToggleSwitch group

Vue usage

Props

Events

Slots

CSS-only version

Markup structure

With description

With visually-hidden label

Initially on

Disabled