The Autocomplete widget is a text input that allow to quickly find and filter values from a list of resources.

By entering some text in the filed, the Autocomplete controller starts searching for entries that match the search string and displays a list of possible results. The search can start immediately as you type a single letter or after 2, 3 or more letters.

Data is provided to the Autocomplete by a Resource Handler that can pull elements locally or from a remote source. Local handlers are the best choice for small/medium datasets and give you the fastest way of retrieving data, remote handlers are necessary for large datasets like point of interests around the world.

This input also provides keyboard navigation allowing you to navigate thorugh and select an option with the keyboard. Additionally it can be configured to automatically highlight and/or select one of the options if this matches exactly what you typed already in the field.

This article will show you how to

  • include an Autocomplete widget in your template
  • use the default Label-Code Resource Handlers for local entries
  • define your own Resource Handler, either for more advanced suggestions of for remote data
  • customize look-and-feel and behavior

The whole list of configuration parameters is available in AutocompleteCfg Bean.

Basic AutoComplete

Label-Code Resource Handlers accepts an Array of suggestions described as Objects matching the LC Resources Handler Bean. Alternatively, we can pass a Configuartion Object while instantiating LC Resource Handler which allows user to set their own labelKey, codeKey, sortingMethod, codeExactMatch, threshold. If no configuartion object is passed to LC Resource Handler, it will take codeKey as code, labelKey as label and the default sorting method as descending alphabeticall order.

Each of the item contains a pair of labelKey(defined in configuartion object) and codeKey(defined in configuartion object) where labelKey is the visible value, codeKey is what is stored internally in the Autocomplete or in the datamodel.

The resources for the Autocomplete in this samples are the nations that participated in the 1966 Football World Cup, start typing the name of a nation and you'll get a list of results.

You can navigate the results with up/down key and select the highlighted option pressing tab or enter. Esc key closes the dropdown without selecting anything.

By default, preselect is set to strict so typing the exact short code of a nation selects that option (you can try typing ENG, FRA, ...). For more samples on preselect please have a look at the paragraph #highlight-behavior.


Being a Text Input you can customize the field width, the label (text, width, position, align), the initial displayed value, the helptext and the status (mandatory, readOnly or disabled) as in any other Input. For reference you can check the samples in textfield.

AutoComplete specific options are

  • expandButton to show a button that opens the whole list of suggestions. A sample is available in the previous paragraph.
  • spellCheck to enable/disable native spell check from the browser. Note that some old browsers don't support spell check, something visually similar can be obtained using sclass underlineError.
  • suggestionsTemplate to provide a different template for the list of options. This gives you the maximum flexibility.

This sample uses a custom resource handler that extends from LCResourceHandler and uses also a customized suggestions template in order to display spellcheck suggestions. Try typing fraance or any other country doubling its third letter and you'll see spellcheck in action.

The second AutoComplete in the previous samples uses the sclass underlineError to change the style of a field in error.

Highlight Behavior

  • autofill is enabled by default. If enabled, when you navigate with up/down keys the value of highlighted option is set in the text field.

To see the difference, type s in the field and press down key, in the first AutoComplete Switzerland is highlighted and set in the field, in the second one the option is only highlighted but the field still contains only the letter s.