December 2, 2013

5 jQuery UI Autocomplete Examples

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.

  1. Using Label-Value Pairs
  2. Add CSS Class to the Dropdown
  3. Load Data via AJAX
  4. Highlight Matched Text
  5. Custom HTML in Dropdown
jQuery UI Autocomplete

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 label and/or value (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 focus and select events

Add CSS Class to the Dropdown

Upon initialization, the autocomplete widget adds the following classes to the associated elements:

  • ui-autocomplete-input to the input field
    • ui-autocomplete-loading to the input field when autocomplete is loading remote data
  • ui-autocomplete to 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 widget method
  • 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 focus and select events
  • 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 _renderItem to 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 focus and select events
  • How to display a loading graphic when autocomplete is waiting for AJAX response
  • How to use _renderItem to customize the display of autocomplete items