The jQuery UI Autocomplete widget enables users to quickly find and select from a list of values as they type. If you find the jQuery UI Autocomplete demos and documentation too daunting, here are some examples with explanation to get you started.
- Using Label-Value Pairs
- Add CSS Class to the Dropdown
- Load Data via AJAX
- Highlight Matched Text
- Custom HTML in Dropdown
A note before you begin: the autocomplete data should look like one of the following regardless of the source option:
- An array of strings e.g.
['Option 1', 'Option 2'] - An array of objects; each object having
labeland/orvalue(and additional) properties e.g.[{label: 'Option 1'}, {label: 'Option 2'}][{value: 'Value 1'}, {value: 'Value 2'}][{label: 'Option 1', value: 1}, {label: 'Option 2', value: 2}]
If necessary, the widget normalizes the data behind the scenes to match the last format in the above mentioned list.
Using Label-Value Pairs
The default behavior of autocomplete is to display the labels in the dropdown menu and insert the value of the focused/selected item in the associated textbox. This makes sense but it may not be desirable. In order to display the label inside the textbox and insert the value in another textbox (or hidden field) you must cancel the focus and select events and manipulate the textbox values yourself. The following example demonstrates:
- How to use local data
- How to override
focusandselectevents
Add CSS Class to the Dropdown
Upon initialization, the autocomplete widget adds the following classes to the associated elements:
ui-autocomplete-inputto the input fieldui-autocomplete-loadingto the input field when autocomplete is loading remote data
ui-autocompleteto the suggestion dropdown
To customize an specific instance of autocomplete widget, use the widget method to grab the UL element that contains the corresponding autocomplete menu; then use CSS classes or inline styles to stylize the element. The following example demonstrates:
- How to use the
widgetmethod - How to add CSS class to one autocomplete widget
- How to constrain the height of the widget using CSS
Load Data via AJAX
There are at least two ways to make the autocomplete widget work with remote/3rd party data; the most flexible way is to use a JavaScript function as the source option. This allows autocomplete to work with server side script's request/response formats i.e. you don't have to change the server side script to work with autocomplete. When using autocomplete with AJAX, make sure that you set higher value for delay and minLength; otherwise, the widget will bombard the server with too many AJAX requests. The following example demonstrates:
- How to use remote data via AJAX using a JavaScript function as the
source - How to transform arbitrary JSON data to
{label: ..., value: ...}format for autocomplete - How to override
focusandselectevents - How to display a loading graphic when autocomplete is waiting for AJAX response
Highlight Matched Text
Wouldn't it be nice if the autocomplete widget highlight the matched part in the suggestion dropdown? You can use the _renderItem extension point to modify the <LI> elements in the suggestion dropdown. There are multiple ways to override an extension point; I will concentrate on one. The following example demonstrates:
- How to use local data
- How to use
_renderItemto customize the display of autocomplete items - How to highlight text within HTML using DOM functions
Custom HTML in Dropdown
The autocomplete widget renders the labels literally even if they include HTML. To display custom HTML inside the suggestion dropdown you could override the _renderItem extension point. The suggestion dropdown is a <UL> element that contains a bunch of <LI> elements, each containing one <A> element. To display custom HTML, append text nodes/HTML elements to it. The following example demonstrates:
- How to use remote data via AJAX
- How to transform arbitrary JSON data to
{label: ..., value: ...}format for autocomplete - How to override
focusandselectevents - How to display a loading graphic when autocomplete is waiting for AJAX response
- How to use
_renderItemto customize the display of autocomplete items
