Accessible Autocomplete (a.k.a Combobox)

Comboboxes are text input fields with autocomplete. In HTML5, they can be implemented using the <datalist> tag. In ARIA, they can be implemented with the combobox role and a bit of JavaScript.

This is one of the rare cases where the native HTML5 version is not accessible in the majority of the web browsers out there. Because of this, I have spent a lot of time working on Enable's combobox implementation.

Example 3: Using HTML5 datalist

This does not work with assistive technologies in most web browsers.

Ironically, this seems to be inaccessible compared to the ARIA version:

• The autocomplete features are not available to mobile screen reader users. I was not able to figure out how to gain access to the datalist values using either Talkback/Chrome on Android or VoiceOver/Safari for iOS.
• When a user types in values, the screen reader doesn't report that is a suggestion list visible in some browsers (e.g. Firefox 86 with NVDA).
• If the user uses the up and down arrow keys, some browsers doesn't read these values out (e.g. older versions of Safari with VoiceOver).
• The autocomplete features do not appear at all in Firefox for Android (at the time of this writing, it was version 96).
• Because of the above reasons, it is one of the cases where ARIA works better.

Enable's ARIA combobox.

This combobox works better with screen readers than the native HTML5 version

This solution described below is available as an NPM module. (Module installation instructions)

This is a heavily refactored version of the combobox example at webkit.org. Added was a few extra instructions and UX features for screen reader users so they could use and understand the autocomplete features in this widget. If you start typing into the combobox, screen readers will tell users when autocomplete items appear and how many there are.

Enter a fruit or vegetable

As you type, press the enter key or use the up and down arrow keys to choose the autocomplete items.

Submit

Autosubmit Using an ARIA Combobox

This is a feature of the NPM module described in the previous section. (Module installation instructions)

There are many e-commerce sites that have a search form with a combobox that submits when the user chooses one of the options. This section shows an accessible proof-of-concept.

Search for your favourite 1980s Video Game:

Please choose a value using the arrow keys or clear the combobox by either pressing the escape key or activating the clear button. Pressing enter will search for the item on Google.

As you type, use the up and down arrow keys or press ENTER and swipe to choose the autocomplete items.

Submit

ARIA Combobox With Categories

This is an experimental feature of the NPM library described in the previous section (Module installation instructions)

Another ARIA combobox example, this time with the options grouped into categories. Note the special formatting in the dropdown. This is common in a lot of modern searchboxes in the headings of a lot of e-commerce sites.

Enter a name of a country or de jure sovereign state

As you type, use the up and down arrow keys (or swipe left and right) to choose the autocomplete items.

Submit

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.

Important Note On The CSS Classes Used In This Module:

This module requires specific CSS class names to be used in order it to work correctly. These CSS classes begin with enable-combobox__. Please see the documentation above to see where these CSS classes are inserted.

Using NPM/Webpack to load ES6 Modules:

1. Install the enable-a11y NPM project.
2. Edit your webpack.config.json file to resolve the ~ modifier by adding the following:
   Wrap text

   ☜ Scroll to read full source ☞

   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') }, ... }, ... }
3. You can use the module like this:
   Wrap text

   ☜ Scroll to read full source ☞

   // import the JS module import combobox from '~enable-a11y/js/modules/combobox'; // import the CSS for the module import '~enable-a11y/css/combobox'; // How to initialize the combobox library combobox.init(); // If you are adding a new instance of this component after page load, // then do the following (where el is the DOM node of the newly created // element, which contains the CSS class .enable-combobox): el.add();
4. Alternatively, if you are using LESS you can include the styles in your project's CSS using:
   Wrap text

   ☜ Scroll to read full source ☞

   @import '~enable-a11y/css/combobox';
   (If you are using it in your CSS, you will have to add the .css suffix)

Using NPM/Webpack to Load Modules Using CommonJS Syntax

1. Install the enable-a11y NPM project.
2. You can import the module using require like this:
   Wrap text

   ☜ Scroll to read full source ☞

   var combobox = require('enable-a11y/combobox').default; ... combobox.init();
3. You will have to include the CSS as well in your project's CSS using:
   Wrap text

   ☜ Scroll to read full source ☞

   @import '~enable-a11y/css/combobox';

Using ES6 modules natively.

This is the method that this page you are reading now loads the scripts.

1. Grab the source by either using NPM, grabbing a ZIP file or cloning the enable source code from github.
2. If you want to load the module as a native ES6 module, copy js/modules/combobox.js , and css/combobox.css from the repo and put them in the appropriate directories in your project (all JS files must be in the same directory).
3. Load the CSS in the head of you document:
   Wrap text

   ☜ Scroll to read full source ☞

   <html> <head> ... <link rel="stylesheet" href="path-to/css/combobox.css" > ... </head> <body> ... </body> </html>
4. Load your scripts using the follwing code (NOTE: you must use <script type="module">):
   Wrap text

   ☜ Scroll to read full source ☞

   <script type="module"> import combobox from "path-to/combobox.js" combobox.init(); </script>

Using ES4