Toggle ​

Use toggle switches to present each option as an on/off switch. Toggles are best used for changing the state of system features.

Usage ​

<script lang="ts" setup>
import { Toggle } from '@returnless/focus-ui';
</script>

<template>
  <Toggle label="Toggle element" help-text="Customers will only be able to check out as guests." :model-value="false" />
  <Toggle label="Toggle element" help-text="Customers will be able to check out with a customer account or as a guest." :model-value="true" />
</template>

Disabled toggle ​

<script lang="ts" setup>
import { Toggle } from '@returnless/focus-ui';
</script>

<template>
  <Toggle label="Toggle element" help-text="Customers will only be able to check out as guests." :model-value="false" disabled />
  <Toggle label="Toggle element" help-text="Customers will be able to check out with a customer account or as a guest." :model-value="true" disabled />
</template>

Best practices ​

Toggles should:

• Always be used with an associated label component.
• Be part of a one or more switches that:
  • List options in a rational order that makes logical sense.
  • Have a default option selected whenever possible.

Accessibility ​

Screen readers convey the state of the toggle automatically. The toggle is read as "on" or "off" when the user navigates to it.

• Use the disabled prop to apply the HTML disabled attribute to the toggle. This prevents users from being able to interact with the toggle, and conveys its inactive state to assistive technologies.
• Use the id prop to provide a unique id attribute value for the toggle. If an id isn't provided, then the component generates one. All toggle switches must have a unique id attribute value to work correctly with assistive technologies.

Labeling ​

• The required label prop conveys the purpose of the toggle to all users.
• Use the labelHidden prop to visually hide the label while still making it accessible to assistive technologies.
• When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute.

Keyboard support ​

• Move focus to the toggle using the tab key (or shift + tab when tabbing backwards)
• Use the up and down arrow keys to change which toggle is selected.