ToggleSwitch

A sliding boolean input used to enable or disable options.

ToggleSwitch is similar to Checkbox, but meant for circumstances where the target can be "on" or "off" rather than "checked" or "unchecked."

For a single switch, the v-model value will be a boolean true when the switch is "on" and false when "off".

For multiple 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").

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.

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 screen reader accessibility.

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>

Usage

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 ​

Demos ​

Configurable ​

Single switch with label and description ​

Form field ​

ToggleSwitch group ​

Usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

With description ​

With visually-hidden label ​

Initially on ​

Disabled ​

ToggleSwitch

Demos

Configurable

Single switch with label and description

Form field

ToggleSwitch group

Usage

Props

Events

Slots

CSS-only version

Markup structure

With description

With visually-hidden label

Initially on

Disabled