jQuery accessible autocomplete list (with some ARIA)

Find/fork me on Github

Other accessible plugins

This jQuery plugin will transform and enhance a simple text input with a datalist into a wonderful and shiny input with autocomplete.

Simple first example, using beers:


(use “Kr” to see some suggestions)

Second simple example in the same page (no tab option activated):

Let’s say we want it in another language, case-sensitive with suggestions displayed when only two characters will be typed, configured in a total different way and we are going to speak french for one of the best things in the world in France, bakeries and pâtisseries:


(utilisez « Cr » pour voir plusieurs suggestions)

Third simple example:

Other options: the suggestion list is limited to 3 results, the search will be made in all suggestions containing the value (not only at the beginning of the suggestions), and the “see more” option will launch an alert.


(use “Kro” to see some suggestions)

How it works

This plugin:

Why it is cool

As it is made using progressive enhancement, if the JavaScript fails to load or is blocked by your visitor, your website will still be ok.

It is accessible: it works with VoiceOver, NVDA, Jaws, and it loves keyboard.

It is easy to customize: there is a default configuration that can be changed/adapted, and you can override it using data-* attributes if you need it.

For the design, you can also customize the CSS to fullfil your needs.

Last updates

27th of June 2017: fixed mistakes in NPM package.json, and updated URL as kindly reported by @felixgirault.

15th of April 2017: fixed an issue on spellcheck attribute value, as kindly reported by @goetsu.

15th of April 2017: linted and re-indented properly code.

20th of August 2016: added options for limiting number of results, searching suggestions containing/beginning text, “see more” text, suggested by @Devtr0n .

7th of July 2016: added min length option, suggested by @rodricifuentes1 .

How to use it

First, add a class js-combobox on an input with a working datalist:

<input type="text" name="mysuper_field" id="id_mysuper_field" class="js-combobox" list="beers" data-combobox-prefix-class="combobox" />
 <datalist id="beers">
  <option value="Meteor">
  <option value="Pils">
  <option value="Kronenbourg">
  <option value="Kronenbourg 2 (for test)">
  <option value="Kronenbourg 3 (for test)">
  <option value="Grimbergen">
 </datalist>

Then download the plugin:

jQuery accessible autocomplete list on Github

and use jQuery of course :)

You may use some options, so have a look at plugin options.

This plugin is available on NPMjs.com and can be installed using npm i jquery-accessible-autocomplete-list-aria.
It is also available on Bower, and can be installed using bower install jquery-accessible-autocomplete-list-aria.

How to style it

In these examples, I’ve used data-combobox-prefix-class="combobox", which means all classes will be prefixed by combobox-. Here are minimal styles needed:


.invisible {
  border: 0;
  clip: rect(0 0 0 0);
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}

.combobox-container {
  position: relative;
  max-width: 250px;
}

.combobox-suggestions {
  position: absolute;
}
.combobox-suggestion {
  cursor: pointer;
}

.combobox-clear-button {
  position: absolute;
  right: 1px;
  font-family: inherit;
  font-size: 1em;
  padding: .5em;
  background: transparent
}

Here is a full example really nicer and more pleasant to use:


.invisible {
  border: 0;
  clip: rect(0 0 0 0);
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}

.combobox-container {
  position: relative;
  max-width: 250px;
  margin: 0 auto;
}

.combobox-suggestions {
  position: absolute;
  left: 0;
  width: 250px;
  background: #fff;
}
.combobox-suggestion {
  color: #666;
  border-bottom: 1px solid #000;
  border-left: 1px solid #000;
  border-right: 1px solid #000;
  cursor: pointer;
  text-align: left;
}
.combobox-suggestion:first-child {
  border-top: 1px solid #000;
}
.combobox-suggestion:hover,
.combobox-suggestion:focus {
  color: #000;
}

.combobox-clear-button {
  position: absolute;
  right: 1px;
  font-family: inherit;
  font-size: 1em;
  padding: .5em;
  background: transparent
}

/* http://geektnt.com/how-to-remove-x-from-search-input-field-on-chrome-and-ie.html */
.js-combobox[type=text]::-ms-clear { display: none; width: 0; height: 0; }
.js-combobox[type=text]::-ms-reveal { display: none; width: 0; height: 0; }

With these styles, the focus/hover looks far better, and a border is added aroung suggestion list.

Options

At the beginning of the plugin, a global configuration is available:

var $js_combobox = $('.js-combobox'),
 $body = $('body'),
 default_text_help = 'Use tabulation (or down) key to access and browse suggestions after input. Confirm your choice with enter key, or esc key to close suggestions box.',
 default_class_for_invisible_text = 'invisible',
 suggestion_single = 'There is ',
 suggestion_plural = 'There are ',
 suggestion_word = 'suggestion',
 button_clear_title = 'clear this field',
 button_clear_text = 'X',
 case_sensitive = 'yes',
 min_length = 0, 
 limit_number_suggestions = 666,
 search_option = 'beginning', // or 'containing'
 see_more_text = 'See more results…',
 tablo_suggestions = [];

You may adapt texts to your need with it. However, if you need to customize one autocomplete field, you may use data-* attributes to override global configuration. Here is the list:

Have a look at the second example if you want to see data attributes in action.

Keys

When focus is on the text input

When focus is on the suggestions

Other informations

License

No license problem, it uses MIT license, so it’s free, open-source and you can do whatever you want with it, including commercial use. This permission notice shall be included in all copies or substantial portions of it.

However, it is not prohibited to tell me that you’ve used it, or send me a little “thank you”. ;)

Weight

It is lightweight: 19kb(development), 6.8kb (minified), only 2.1kb minified and gzipped.

Tribute

The idea of this script is inspired by Heydon’s basic autocomplete with listbox demo. Aurélien Levy enhanced it with a working prototype, and I’ve finished the work (packaging, reutilisability, progressive enhancement, etc.) with Aurélien.