Toggle

A toggle, or "switch", is a button control element that allows the user to make a binary selection.

Preview

Usage

The Toggle component acts as a way to allow the User to switch between two mutually exclusive options. While it technically mirrors a Checkbox state, its effect on the system is immediate—much like a light switch immediately turns on or off the lights. In contrast, the checked state of a Checkbox won't be applied until a separate action to confirm the selection is taken.

Do

When its action has an instantaneous effect.

Don’t

When its action does not have an immediate effect on the application.
Selecting between 2 options. Instead, utilize a Checkbox.
As an alternative to a Checkbox or Radio within a Form.

Best Practices

A Toggle component should be used as a control within an application and provide a way to toggle between two states like a household light switch.
An indeterminate Toggle convey a "mixed" state that neither qualifies as toggled or not toggled. An example use case is when a Toggle acts as a "parent" of a collection of child Toggle components:
- Toggled: all children are toggled.
- Not toggled: all children are not toggled.
- indeterminate: children are a mix of toggled and not toggled.

Variants and Examples

Base Styles

Sizes

With v-model

Vue API

Slots

Name	Description
default	Slot for the main content

Props

Name	Description	Default
disabled	Disables the toggle interactions Type: boolean Values: truefalse	false
id	The id of the toggle Type: string	function() { return getUniqueString(); }
labelChildProps	A set of props that are passed into the label container Type: object	{}
labelClass	Used to customize the label container Type: string\|array\|object	''
showIcon	Shows the icon Type: boolean Values: truefalse	true
size	The size of the toggle. Type: string Values: smmd	'md'
toggleOnClick	Whether the component toggles on click. If you set this to false it means you will handle the toggling manually via the checked prop or v-model. Change events will still be triggered. Type: boolean Values: truefalse	true
v-model	Value of the toggle Type: boolean\|string Values: truefalse'mixed'	false
wrapperClass	Additional styling for the wrapper element Type: string\|array\|object	undefined

Events

Name	Description
change	Toggle change event Type: Boolean
update:modelValue	v-model event event Type: Boolean

Classes

Class	Applies to	Description

Accessibility

This component uses a native button element under the hood that has a role switch and type button to improve accessibility. See W3C guidelines for more information.

The best accessibility is semantic HTML. Most screen readers understand how to parse buttons if they’re correctly formatted. When it comes to toggles, there are a few things to keep in mind:

All toggle buttons should have an id attribute.
Associate toggle labels with their buttons using the for attribute. This correlates with the toggle's id.
If you have a group of related toggles, use a fieldset to group them and a legend to title the group. For further information, please visit Gov.UK’s article, "Using the fieldset and legend elements".

Button

The button element should be fully accessible by keyboard. To accomplish this, the DtToggle component automatically populates several ARIA attributes to the underlying button element depending on the checked and disabled states. However, if a label default slot is not used with DtToggle (without including an aria-label), a console warning error will be thrown indicating that this issue exists.

Focus & Keyboard

The button element should capture keyboard focus as long as it is not disabled (disabled prop is true). ENTER key will emit a change event with the current value of the toggle and will change its internal checked state.

Preview

Usage #

Do

Don’t

Best Practices #

Variants and Examples #

Base Styles #

Sizes #

With v-model #

Vue API #