ARIA Switch button component
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

ARIA Switch Button

Similar to a toggle button or checkbox, a switch button is meant to be used when its visual appearance most resembles an "on and off" "switch".

The expected user experience of a switch button is for an immediate action to take place. For instance, toggling a light/dark theme for a site or application, where the theme change instantly takes effect.

In contrast, when interacting with a checkbox, any change in UI state is typically expected to occur after a purposeful form submission by the user. See related WCAG success criteria "on input".

A toggle button and switch may seem similar in functionality and purpose, but their differences become more apparent if you focus on the semantics, typical visual treatments, and announcements of each.

In browsers and screen readers that support both elements, a toggle button is typically announced as "pressed" in its active state, where a switch is announced as "on". A toggle button may be grouped within a series of toggle buttons, where activating one may deactivate another. A switch ideally is an independent UI component, and should not be modified by outside controls.

For more information about the Switch Role, and its differences to toggle buttons and checkboxes, please visit:

How does it work?

The baseline for this component requires the following markup:

<button type="button" 
  <!-- Meaningful label here -->

The data-action="aria-switch" is required for the switch component to work. All setup and functionality is based around this attribute.

The reason for the button being disabled by default is that this component requires JavaScript to function. Without JavaScript, users should be aware there is a component that is currently unusable. When JavaScript is enabled, the disabled attribute will be removed from the switch, unless a data-keep-disabled attribute is present.

role="switch" is required to accurately announce this component by screen readers that support the switch role. If this attribute is missing, or if it is set to another role, the JavaScript will update it to the appropriate switch value.

An aria-checked attribute should be set to announce the current state of the switch. If this attribute is not present, the script will default to setting an aria-checked="false", but that's not helpful for users with blocked JavaScript. So again, remember to set this attribute.

Use the aria-labelledby to point to a text label that this switch will control the state of. If a visible label is not present (e.g. you're using an icon of some sort, or somehow it's visually apparent what this switch does without a visible label), be sure to use an aria-label instead to give context as to what this switch is toggling on/off.

Currently there is no fall back for setting an appropriate label or labelledby value to this component, if one is not manually set. Instead a console error is purposefully left in the script to alert developers of this failure for when a switch is missing these attributes.

Screen Reader Quirks

Note that since 2017, and tested again with VoiceOver on iOS 11.3 & 11.4, VoiceOver continues to have issues with role="switch" elements. VoiceOver will fall back to announcing switches as checkboxes, but with bugged behavior, where the state is not announced.

JAWS 2018 + IE11 also experience issues with switches.

NVDA 2018.2.1 + FireFox and Chrome will announce elements with role="switch" as "not pressed" and then announce whether they are checked or not. It doesn't matter the current state of whether the switch is checked or not, it will always announce "not pressed." This can be incredibly confusing to determine the actual state of these elements since both checked and pressed states are announced.

Depending on your audience and the devices / browsers they use, you may want to use caution before fully embracing switches without suitable fall backs.

License & Such

This script was written by Scott O'Hara.

It has an MIT license.

Do with it what you will :)