ToggleSwitch

Accessibility and usability expectations

A ToggleSwitch must have a clear, descriptive, and permanently visible label so that users understand the purpose of the input.

If there is additional information about the setting, these should be provided as a caption underneath the control.

The text must meet the minimum contrast requirements of 4.5:1.

The control must have a minimum contrast ration of 3:1 against the background.

A ToggleSwitch must have a visible focus style. Instead of using the browser's default focus style, which can be difficult to see against certain backgrounds, a custom focus style should be implemented. A custom focus style must have a minimum contrast ration of 3:1 against the background.

The target size and spacing of the control must be at least 24 by 24 CSS pixels.

The text must be resizable and the text spacing adjustable, and content must remain by readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels.

Unless a ToggleSwitch is disabled, it must by focusable using the Tab key, and pressing the Space key, and optionally the Enter key, will toggle the switch.

A ToggleSwitch must not trap focus or initiate a change of context when focused or activated.

The control must have an accessible name that is announced by screen readers. The accessible name must match or include the visible label, so that that speech recognition users can activate a ToggleSwitch by saying the visible text label. Additional content must be easily discoverable by screen reader users - in general, by having them programmatically associated with the input using aria-describedby.

A ToggleSwitch must have an appropriate role and state so that screen readers users know that it is a control that can be toggled.

A ToggleSwitch's on/off state must be conveyed to screen readers.

If a ToggleSwitch is disabled, the disabled state must be conveyed to screen readers.

If a ToggleSwitch is in a loading state, the state must be conveyed to screen readers.

Built-in accessibility features

The label, caption, control and custom focus style meet minimum contrast requirements.

The text is resizable and the text spacing adjustable.

The component uses the native <button> with aria-pressed applied, so screen readers users know that it is a control that can be toggled and it has the correct keyboard behaviour.

When the ToggleSwitch is disabled, the disabled attribute is applied and the disabled state conveyed to screen readers.

Implementation requirements

Provide a descriptive visible label, in a semantically neutral element. Make the visible label the accessible name of the ToggleSwitch by applying aria-labelledby to the ToggleSwitch and referencing the id of the label.

<div id="label">Email</div>
<ToggleSwitch aria-labelledby="label"  />

If the ToggleSwitch has a caption, associate the caption using aria-describedby.

<div id="label">Email</div>
<ToggleSwitch aria-labelledby="label" aria-describedby="caption"  />
<div id="caption">A digest will be sent weekly</div>

Make sure the component reflows when zoomed or viewed at a width equivalent to 320 CSS pixels.

When setting the loading property, the component will include a visual spinner. Note that this spinner is not conveyed to screen readers. You will need to use additional methods (such as a visually hidden live region notification) to convey this state to screen reader users. See the documentation for loading for further details.

Touch target

When the UI is rendered on a touch-screen device, ensure that the ToggleSwitch has a large enough touch target size. The ToggleSwitch should respond to hovers, clicks, and taps anywhere in the touch target area, even if it isn't directly on the control.

Edit in Figma

How to test the component

Integration tests

• The ToggleSwitch has a sufficiently descriptive visible label
• The label is associated with the <button> using aria-labelledby
• If there is a caption, it is associated with the <button> using aria-describedby
• If the ToggleSwitch has a loading state, the state is conveyed to screen reader user, such as a visually hidden live region notification

Component tests

• The label, status text and caption meet the minimum contrast requirements of 4.5:1
• The control border and custom focus style meets the minimum contrast requirement of 3:1
• The content remains readable, without requiring horizontal scrolling, when zoomed or viewed at a width equivalent to 320 CSS pixels
• The control meets the minimum target size of 24 by 24 CSS pixels
• The component renders a <button> with aria-pressed applied. In the off state aria-pressed is set to false, in the on state true
• If the ToggleSwitch is disabled, the disabled attribute is present on the <button>