Toggle

Toggles are used to switch between two possible states

Toggles can be used to:

  • Switch something on or off
  • Switch between two different states
  • To select standalone options that can be controlled independently
  • When the changes need to take effect immediately once selected
  • To switch between on/off or enabled/disabled states
  • To switch between two different but equal states
  • To select several related options in a list. Use the checkbox component.
  • To select a single option in a list. Use the radio component.
  • If it’s necessary to save option(s) before they take effect.
  • To allow users to agree or disagree with permissions such as terms and conditions. Use the checkbox component.

Live example

Storybook failed to load. Please connect to the VPN to access.

Availabile platforms

Platform

Available

Figma

v3+

Web (@ovotech/element)

v3+

App (@ovotech/element-native)

v3+


How to use it

Toggles are the best way to let users adjust settings. This could be turning something on or off or enabling or disabling a function. The impact of changing a toggle should be immediate without the user needing to save.

Toggles can also be used to switch between two different but equal states. If a toggle changes a visible state, such as making more options available, or changing parameters of a graph, this should be seen immediately when the toggle is switched‌.

Row height, including text, must be a minimum of 44px on touch screens.

Label text

Toggles should always have a label next to them to identify what they do.

  • Labels can either describe an object or an action. For example, “Email notifications” or “Show dates”.
  • Labels should be short and direct so they’re easily scannable.
  • Labels should have keywords first. For example, “Meter reading notifications” as opposed to “Turn on notifications for meter readings”.
  • Labels should be unique.

If listing more than 10 toggles together, consider grouping them using sub-headings or tabs to make it easier to scan through the options.

Hint text

Adding hint text to a label is optional. Ideally, labels should be as descriptive as possible so hint text can be avoided as it may impact scannability. Hint text should only be used to add a description where necessary.

Warnings

Unlike other selection components, toggles won’t have an error state since either state is possible. However,‌ switching a toggle may result in an unforeseen outcome. For example, turning off data collection may impact the accuracy of information we can provide the user. Hint text can be used to explain this. But if hint text is already in use, it may be necessary to have this information appear using another component such as a notification or toast.

Label position

By default the label relating to a toggle is positioned to its left and space apart, but this can be switched to a right alignment with minimal spacing as an alternative using the labelPosition property.

A collection of toggle should follow the same pattern within an interface, with a mix of alignments being undesired.

Accessibility

User stories

The following user stories can be used to understand when this component should be used, and how to know when it's been implemented correctly.

  • As someone using the component, I want to understand the label associated with each toggle.
  • As someone with a cognitive disability, I want to be able to understand the information required from me, and the options I can choose between.
  • As a keyboard-only user, I want to be able to navigate to each of the toggles and then activate them using the Space key.
  • As someone with a motor disability, I want to be able to easily select the correct toggle.
  • As a screen reader user, I want the group label about the toggles to be announced when navigating through the toggles.
  • As a screen reader user, I want any additional information provided alongside the group label to be announced when navigating through the toggles.
  • As a screen reader user, I want the toggle's label and its state to be announced when I navigate to it.
  • As a voice-control user, I want to be able to select a toggle using its associated label.

Test steps

Use these steps to check that the Toggle component has been implemented correctly:

  1. Turn on a screen reader.
  2. Navigate to the toggle(s).
  3. Verify that each toggle has a visible label.
  4. Verify that when navigated to, both the toggle's label and the group label are announced and that these match those visually present.
  5. Verify that the toggle can be activated using the Space key.
  6. Verify that a screen reader correctly announces the toggle's state.

Properties

Name

Values

Default

id (required for web)

string

 

label

string | ReactNode

 

checked

boolean

false

hint

ReactNode

 

labelPosition

'left' | 'right'

left

onChange

Function

 

error

string

 

optional

boolean

 

 





  • xxx