QuickNav

Options

appendTo
autoFocus
delay
disabled
minLength
position
source

Methods

close
destroy
disable
enable
option
search
widget

Events

change
close
create
focus
open
response
search
select

Autocomplete Widgetversion added: 1.8

Description: Autocomplete enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

Options

appendToType: Selector

Default: "body"
Which element the menu should be appended to. Override this when the autocomplete is inside a position: fixed element. Otherwise the popup menu would still scroll with the page.

autoFocusType: Boolean

Default: false
If set to true the first item will automatically be focused when the menu is shown.

delayType: Integer

Default: 300
The delay in milliseconds between when a keystroke occurs and when a search is performed. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.

disabledType: Boolean

Default: false
Disables the autocomplete if set to true.

minLengthType: Integer

Default: 1
The minimum number of characters a user must type before a search is performed. Zero is useful for local data with just a few items, but a higher value should be used when a single character search could match a few thousand items.

positionType: Object

Default: { my: "left top", at: "left bottom", collision: "none" }
Identifies the position of the suggestions menu in relation to the associated input element. The of option defaults to the input element, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.

sourceType: Array or String or Function( Object request, Function response( Object data ) )

Default: none; must be specified
Defines the data to use, must be specified.

Independent of the variant you use, the label is always treated as text. If you want the label to be treated as html you can use Scott González' html extension. The demos all focus on different variations of the source option - look for one that matches your use case, and check out the code.

Multiple types supported:
  • Array: An array can be used for local data. There are two supported formats:
    • An array of strings: [ "Choice1", "Choice2" ]
    • An array of objects with label and value properties: [ { label: "Choice1", value: "value1" }, ... ]
    The label property is displayed in the suggestion menu. The value will be inserted into the input element when a user selects an item. If just one property is specified, it will be used for both, e.g., if you provide only value properties, the value will also be used as the label.
  • String: When a string is used, the Autocomplete plugin expects that string to point to a URL resource that will return JSON data. It can be on the same host or on a different one (must provide JSONP). The Autocomplete plugin does not filter the results, instead the request parameter term gets added to the URL, which the server-side script should use for filtering the results. The data itself can be in the same format as the local data described above.
  • Function: The third variation, a callback, provides the most flexibility and can be used to connect any data source to Autocomplete. The callback gets two arguments:
    • A request object, with a single term property, which refers to the value currently in the text input. For example, if the user enters "new yo" in a city field, the Autocomplete term will equal "new yo".
    • A response callback, which expects a single argument: the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data. It's important when providing a custom source callback to handle errors during the request. You must always call the response callback even if you encounter an error. This ensures that the widget always has the correct state.

Methods

close()

Closes the Autocomplete menu. Useful in combination with the search method, to close the open menu.

destroy()

Removes the autocomplete functionality completely. This will return the element back to its pre-init state.

disable()

Disables the autocomplete.

enable()

Enables the autocomplete.

option( optionName ) Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.

option() Returns: PlainObject

Gets an object containing key/value pairs representing the current autocomplete options hash.

option( optionName, value )

Sets the value of the autocomplete option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.

option( options )

Sets one or more options for the autocomplete.
  • options
    Type: Object
    A map of option-value pairs to set.

widget()

Returns a jQuery object containing the menu element. Although the menu items are constantly created and destroyed, the menu element itself is created during initialization and is constantly reused.

Events

change( event, ui )

Triggered when the field is blurred, if the value has changed.
  • event
    Type: Event
  • ui
    Type: Object
    • item
      Type: jQuery
      The item selected from the menu, if any. Otherwise the property is null.

close( event, ui )

Triggered when the menu is hidden. Not every close event will be accompanied by a change event.

create( event, ui )

Triggered when the autocomplete is created.

focus( event, ui )

Triggered when focus is moved to an item (not selecting). The default action is to replace the text field's value with the value of the focused item, though only if the event was triggered by a keyboard interaction.

Canceling this event prevents the value from being updated, but does not prevent the menu item from being focused.

open( event, ui )

Triggered when the suggestion menu is opened or updated.

response( event, ui )

Triggered after a search completes, before the menu is shown. Useful for local manipulation of suggestion data, where a custom source option callback is not required. This event is always triggered when a search completes, even if the menu will not be shown because there are no results or the Autocomplete is disabled.
  • event
    Type: Event
  • ui
    Type: Object
    • content
      Type: Array
      Contains the response data and can be modified to change the results that will be shown. This data is already normalized, so if you modify the data, make sure to include both value and label properties for each item.

select( event, ui )

Triggered when an item is selected from the menu. The default action is to replace the text field's value with the value of the selected item.

Canceling this event prevents the value from being updated, but does not prevent the menu from closing.

By giving an Autocomplete field focus or entering something into it, the plugin starts searching for entries that match and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.

This can be used to choose previously selected values, such as entering tags for articles or entering email addresses from an address book. Autocomplete can also be used to populate associated information, such as entering a city name and getting the zip code.

You can pull data in from a local or remote source: Local is good for small data sets, e.g., an address book with 50 entries; remote is necessary for big data sets, such as a database with hundreds or millions of entries to select from. To find out more about customizing the data soure, see the documentation for the source option.

Keyboard interaction

When the menu is open, the following key commands are available:

  • UP - Move focus to the previous item. If on first item, move focus to the input. If on the input, move focus to last item.
  • DOWN - Move focus to the next item. If on last item, move focus to the input. If on the input, move focus to the first item.
  • ESCAPE - Close the menu.
  • ENTER - Select the currently focused item and close the menu.
  • TAB - Select the currently focused item, close the menu, and move focus to the next focusable element.
  • PAGE UP/DOWN - Scroll through a page of items (based on height of menu). It's generally a bad idea to display so many items that users need to page..

When the menu is closed, the following key commands are available:

  • UP/DOWN - Open the menu, if the minLength has been met.

Additional Notes:

  • This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.

Example:

A simple jQuery UI Autocomplete

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>autocomplete demo</title>
    <link rel="stylesheet" href="http://code.jquery.com/ui/1.9.0/themes/base/jquery-ui.css">
    <script src="http://code.jquery.com/jquery-1.8.2.js"></script>
    <script src="http://code.jquery.com/ui/1.9.0/jquery-ui.js"></script>
</head>
<body>
 
<label for="autocomplete">Select a programming language: </label>
<input id="autocomplete">
 
<script>
$( "#autocomplete" ).autocomplete({
    source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ]
});
</script>
 
</body>
</html>

Demo: