Widget: Autocomplete



Implementing This Widget

Implementing the Autocomplete widget is done when you want to have an accessible ARIA widget that will automatically populate fields with a selection when only a portion of the selection was initially entered, whether done with a mouse or keyboard.


The following rules dictate the data formatting requirements. The data MUST:

  • Be an array: The only acceptable type for data is an array.
  • Contain either strings or items with a 'label' field: Each item in your array must either be a string or an object with a label field which contains a string.
  • Be homogenous: No mixing - either every item in your array is a string, or every item is an object with a label field. You may not mix the two.
To implement the Autocomplete widget
  1. Pass an array of data into createAutocomplete() to get an HTML element back.
  2. Add it to the DOM.

Expected Operation

Start typing into the input field. As you type, items in your data will appear below, constrained to just those items that start with the characters you've typed. Press up or down to navigate through the list (or alt-up and alt-down, if using a screenreader which hijacks control). Press enter to select a given value, which will populate the input with that string and close the list of options. Press escape to close the hints without selecting anything. Press escape again to clear the field.

You may also use a mouse to select an item from the dropdown list.

Form Validation

In order to validate this control, you must call ac.getInputElement() to get a reference to the internal input. You can then apply any validation logic you'd like to it. This example uses the deque form validation library included with these widgets.

Notes for the developer

The official specification insists that this widget should throw an error or present an 'invalid' notification if the user tabs out of it while its value is either (a) empty or (b) invalid. It's up to you, as the developer, to implement compliance with this stipulation when appropriate.

Example Implementation Reference

To view an implementation of this widget, see Autocomplete form example