ToggleSwitch
A sliding boolean input used to enable or disable options.
Unlike Checkbox, ToggleSwitch is meant to be used alone, not in a group.
Current styles support a single toggle switch with or without a label. The label should only be omitted here if one is added and connected with the input via the for
attribute elsewhere (like a future Field component). If you're just using this component by itself, you should include a label.
v-model
value will be boolean.
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
Name | Value |
---|---|
Props | |
alignSwitch | |
disabled | |
Slots | |
default | |
View | |
Reading direction |
Default
Toggle the ToggleSwitch to see the value change. Open up the console to see emitted events.
Toggle switch value: false
With label
Adding content into ToggleSwitch's default slot will generate a <label>
element associated with the <input>
.
ToggleSwitch group
For a group of 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.
ToggleSwitch group value: [ "switch-1" ]
Form field
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.
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 |
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 | Input label content |
CSS-only version
Markup structure
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.