Autocomplete, when added to an input field, enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.
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 enter previous selected values, for example you could use Autocomplete for entering tags, to complete an address, you could enter a city name and get the zip code, or maybe enter email addresses from an address book.
You can pull data in from a local and/or a remote source: Local is good for small data sets (like an address book with 50 entries), remote is necessary for big data sets, like a database with hundreds or millions of entries to select from.
Autocomplete can be customized to work with various data sources, by just specifying the source option. A data source can be:
The local data can be a simple Array of Strings, or it contains Objects for each item in the array, with either a label or value property or both. The label property is displayed in the suggestion menu. The value will be inserted into the input element after the user selected something from the menu. If just one property is specified, it will be used for both, eg. if you provide only value-properties, the value will also be used as the label.
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 request parameter "term" gets added to that URL. The data itself can be in the same format as the local data described above.
The third variation, the callback, provides the most flexibility, and can be used to connect any data source to Autocomplete. The callback gets two arguments:
The demos all focus on different variations of the source-option - look for the one that matches your use case, and take a look at the code.
$("input#autocomplete").autocomplete({ source: ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"] });
<!DOCTYPE html> <html> <head> <link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css" rel="stylesheet" type="text/css"/> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script> <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script> <script> $(document).ready(function() { $("input#autocomplete").autocomplete({ source: ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"] }); }); </script> </head> <body style="font-size:62.5%;"> <input id="autocomplete" /> </body> </html>
Before a request (source-option) is started, after minLength and delay are met. Can be canceled (return false), then no request will be started and no items suggested.
search
event as an init option.
$( ".selector" ).autocomplete({
search: function(event, ui) { ... }
});
search
event by type: autocompletesearch
.
$( ".selector" ).bind( "autocompletesearch", function(event, ui) {
...
});
Triggered when the suggestion menu is opened.
open
event as an init option.
$( ".selector" ).autocomplete({
open: function(event, ui) { ... }
});
open
event by type: autocompleteopen
.
$( ".selector" ).bind( "autocompleteopen", function(event, ui) {
...
});
Before focus is moved to an item (not selecting), ui.item refers to the focused item. The default action of focus is to replace the text field's value with the value of the focused item, though only if the focus 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.
focus
event as an init option.
$( ".selector" ).autocomplete({
focus: function(event, ui) { ... }
});
focus
event by type: autocompletefocus
.
$( ".selector" ).bind( "autocompletefocus", function(event, ui) {
...
});
Triggered when an item is selected from the menu; ui.item refers to the selected item. The default action of select 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.
select
event as an init option.
$( ".selector" ).autocomplete({
select: function(event, ui) { ... }
});
select
event by type: autocompleteselect
.
$( ".selector" ).bind( "autocompleteselect", function(event, ui) {
...
});
When the list is hidden - doesn't have to occur together with a change.
close
event as an init option.
$( ".selector" ).autocomplete({
close: function(event, ui) { ... }
});
close
event by type: autocompleteclose
.
$( ".selector" ).bind( "autocompleteclose", function(event, ui) {
...
});
After an item was selected; ui.item refers to the selected item. Always triggered after the close event.
change
event as an init option.
$( ".selector" ).autocomplete({
change: function(event, ui) { ... }
});
change
event by type: autocompletechange
.
$( ".selector" ).bind( "autocompletechange", function(event, ui) {
...
});
Remove the autocomplete functionality completely. This will return the element back to its pre-init state.
Disable the autocomplete.
Enable the autocomplete.
Get or set any autocomplete option. If no value is specified, will act as a getter.
Set multiple autocomplete options at once by providing an options object.
Returns the .ui-autocomplete element.
Triggers a search event, which, when data is available, then will display the suggestions; can be used by a selectbox-like button to open the suggestions when clicked. If no value argument is specified, the current input's value is used. Can be called with an empty string and minLength: 0 to display all items.
Close the Autocomplete menu. Useful in combination with the search method, to close the open menu.
The jQuery UI Autocomplete plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.
If a deeper level of customization is needed, there are widget-specific classes referenced within the jquery.ui.autocomplete.css stylesheet that can be modified. These classes are highlighed in bold below.
Note: This is a sample of markup generated by the autocomplete plugin, not markup you should use to create a autocomplete. The only markup needed for that is <input/>.