The ARIA Switch Role
A switch is like a checkbox, in that is designed to be an input control that has a binary value
(either checked and unchecked or on or off,
depending on the screen reader).
Like tablists.php, switches do not have a native HTML5 tag, so we implement custom code using
the
switch
role in JavaScript.
Many developers will implement switches using the <input type="checkbox">
, since the native HTML5
checkbox control is already accessible. While you could do this, I would argue this is semantically dishonest: partially
sighted users who use a screen reader hear that the control is a checkbox, but there is no checkmark involved.
My father, who is partially sighted, has fallen in this trap on a website once on his tablet. He was afraid of submitting an order form because he felt that the screen reader was lying to him, and he afraid of making a mistake because he didn't know what the control really did (he wasn't sure what it was, but it certainly didn't look like a checkbox). He tried to explain to me this issue over the phone, and after quite a few minutes not understanding what the trouble was, I went over to his house to see what he was talking about. After looking at his tablet, I learned a valuable lesson: developers shouldn't be dishonest to users to make things easier for themselves.
A simple switch coded with ARIA.
This code is based on information from the
MDN article on
Using
the switch role. The switch reports the checked state as "on" or "off" in VoiceOver
and "checked" or "unchecked" in NVDA and ChromeVox. In order to make some consistency among user agents, an aria-describedby
on the switch can state the "on/off" state to all screen readers. This description is also given visually, to make it obvious what the state is for sighted users. Developers could hide this text with the sr-only
class, and put "off" and "on" labels on sides of the right and left sides of the component if they wish instead.
Code Walkthrough of the Above Example
Below is the HTML of the above example. Use the dropdown to highlight each of the individual steps that makes the example accessible.
Installation Instructions
You can load this JavaScript library into your application in serveral ways:
- as an ES6 module using Webpack.
- as a CommonJS module using
require()
and Webpack. - as a native ES6 module within the browser.
- as an old-school ES4/JavaScript library.
If you haven't done so already, choosing which you should use is obviously a major architectural decision. Here are a few articles that will help you decide:
- Jan Olaf Krems gives a great overview of the JavaScript File Format Differences
- Joe Honton discusses that With ES Modules and HTTP/2 You May Not Need Webpack Anymore
- Stack Overflow has a really good thread about Webpack vs ES6 modules as well.
Using NPM/Webpack to load ES6 Modules:
-
Install the
enable-a11y
NPM project. -
Edit your webpack.config.json file to resolve the
~
modifier by adding the following:module.exports = { ... resolve: { extensions: ['.js', '.jsx', '.scss', '.css', '*.html'], modules: [ path.resolve('./src/js'), path.resolve('./node_modules') ], alias: { '~enable-a11y': path.resolve(__dirname, 'node_modules/enable-a11y') }, ... }, ... }
-
You can use the module like this:
// import the JS module import switch from '~enable-a11y/js/modules/switch'; // import the CSS for the module import '~enable-a11y/css/switch'; // How to initialize the switch library switch.init(); // Note that this component will work with DOM elements coded like // the examples above added after page load. There is no need to call // an .add() method, like we do with the Enable combobox component.
-
Alternatively, if you are using LESS you can include the styles in your project's CSS using:
@import '~enable-a11y/css/switch';
.css
suffix)
Using NPM/Webpack to Load Modules Using CommonJS Syntax
-
Install the
enable-a11y
NPM project. -
You can import the module using require like this:
var switch = require('enable-a11y/switch').default; ... switch.init();
- You will have to include the CSS as well in your project's CSS using:
@import '~enable-a11y/css/switch';
Using ES6 modules natively.
This is the method that this page you are reading now loads the scripts.
- Grab the source by either using NPM, grabbing a ZIP file or cloning the enable source code from github.
-
If you want to load the module as a native ES6 module, copy
js/modules/switch.js
, andcss/switch.css
from the repo and put them in the appropriate directories in your project (all JS files must be in the same directory). -
Load the CSS in the head of you document:
<html> <head> ... <link rel="stylesheet" href="path-to/css/switch.css" > ... </head> <body> ... </body> </html>
-
Load your scripts using the follwing code (NOTE: you must use
<script type="module">
):<script type="module"> import switch from "path-to/switch.js" switch.init(); </script>
Using ES4
Just do the same as the ES6 method, except you should get the JavaScript files from thejs/modules/es4
directory instead of the js/modules/
:
<script src="path-to/es4/switch.js"></script>