Toggle

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.

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 #

<dt-stack as="fieldset" gap="100">
  <dt-toggle class="d-g-200">Unchecked Toggle</dt-toggle>
  <dt-toggle :model-value="true" class="d-g-200">Checked Toggle</dt-toggle>
  <dt-toggle disabled class="d-g-200">Unchecked Disabled</dt-toggle>
  <dt-toggle :model-value="true" disabled class="d-g-200">Checked Disabled</dt-toggle>
  <dt-toggle :model-value="'mixed'" class="d-g-200">Indeterminate Toggle</dt-toggle>
  <dt-toggle :model-value="'mixed'" class="d-g-200" disabled>Indeterminate Disabled</dt-toggle>
  <dt-toggle class="d-g-200" :show-icon="false">Without icon</dt-toggle>
</dt-stack>

Sizes #

<dt-stack as="fieldset" gap="100">
  <dt-toggle :size="200" class="d-g-200">Small size</dt-toggle>
  <dt-toggle class="d-g-200">Default size</dt-toggle>
</dt-stack>

With v-model #

<dt-toggle v-model="checked" class="d-g-200">Toggle</dt-toggle>

Vue API #

import { DtToggle } from '@dialpad/dialtone-vue';

Slots

Props

Events

Classes #

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 an update:modelValue event with the current value of the toggle and will change its internal checked state.