jQuery UI API - Autocomplete Widget

Note: When the suggestion menu is open,appendTothe option should not be changed.

Code examples:

Initialize an autocomplete with the specifiedappendTooption:

$( ".selector" ).autocomplete({ appendTo: "#someElem" });
    

After initialization, get or set theappendTooption:

// getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
 
// setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
    

Code examples:

Initialize an autocomplete with the specifiedautoFocusoption:

$( ".selector" ).autocomplete({ autoFocus: true });
    

After initialization, get or set theautoFocusoption:

// getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
 
// setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );
    

Code examples:

Initialize an autocomplete with the specifieddelayoption:

$( ".selector" ).autocomplete({ delay: 500 });
    

After initialization, get or set thedelayoption:

// getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );
 
// setter
$( ".selector" ).autocomplete( "option", "delay", 500 );
    

Code examples:

Initialize an autocomplete with the specifieddisabledoption:

$( ".selector" ).autocomplete({ disabled: true });
    

After initialization, get or set thedisabledoption:

// getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
 
// setter
$( ".selector" ).autocomplete( "option", "disabled", true );
    

Code examples:

Initialize an autocomplete with the specifiedminLengthoption:

$( ".selector" ).autocomplete({ minLength: 0 });
    

After initialization, get or set theminLengthoption:

// getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
 
// setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );
    

Code examples:

Initialize an autocomplete with the specifiedpositionoption:

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
    

After initialization, get or set thepositionoption:

// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
 
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
    

Regardless of the variable you use, the label is always treated as text. If you want the label to be treated as html, you can useScott González' html extension. The demo focuses onsourcethe different variations of the option - you can find the one that matches your usage and view the related code.

Multiple types are supported:

• Array: An array that can be used for local data. Two formats are supported:
  • String array:[ "Choice1", "Choice2" ]
  • An array of objects withlabelandvalueattributes:[ { label: "Choice1", value: "value1" }, ... ]
  The label attribute is displayed in the suggestion menu. When the user selects an item, the value is inserted into the input element. If only one attribute is specified, that attribute is treated as both the label and the value. For example, if you only providevaluethe attribute, the value is also treated as the label.
• String: When using a string, the Autocomplete plugin expects the string to point to a URL resource that can return JSON data. It can be on the same host or on a different host (must provide JSONP). The Autocomplete plugin does not filter the results, but instead, through atermfield, adds a query string for the server-side script to filter the results. For example, ifsourcethe option is set to"http://example.com", and the user typesfoo, the GET request would behttp://example.com?term=foo. The format of the data itself can be the same as the format of the local data described earlier.
• Function: The third variable, a callback function, provides the greatest flexibility and can be used to connect any data source to the Autocomplete. The callback function accepts two parameters:
  • anrequestobject, with atermattribute, representing the value in the current text input. For example, if the user types in the city field"new yo", then Autocomplete term is equivalent to"new yo"。
  • aresponsecallback function, providing a single parameter: the data suggested to the user. The data should be filtered based on the provided term, and can be in any of the local data formats described above. Used to provide a custom source callback to handle errors during the request. Even if an error is encountered, you must callresponsethe callback function. This ensures the widget is always in the correct state.

  When filtering local data, you can use the built-in$.ui.autocomplete.escapeRegexfunction. It accepts a string argument, escapes all regular expression characters, and makes the result safe to pass tonew RegExp()。

Code example:

Initialize the autocomplete with the specifiedsourceoptions:

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
    

After initialization, get or set thesourceoption:

// getter
var source = $( ".selector" ).autocomplete( "option", "source" );
 
// setter
$( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] );
    

• This method does not accept any arguments.

Code example:

Invoke the close method:

$( ".selector" ).autocomplete( "close" );
    

• This method does not accept any arguments.

Code example:

Invoke the destroy method:

$( ".selector" ).autocomplete( "destroy" );
    

• This method does not accept any arguments.

Code example:

Invoke the disable method:

$( ".selector" ).autocomplete( "disable" );
    

• This method does not accept any arguments.

Code example:

Invoke the enable method:

$( ".selector" ).autocomplete( "enable" );
    

• optionName
  Type: String
  Description: The name of the option to get.

Code example:

Invoke the method:

var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
    

• This method does not accept any arguments.

Code example:

Invoke the method:

var options = $( ".selector" ).autocomplete( "option" );
    

• optionName
  Type: String
  Description: The name of the option to set.
• value
  Type: Object
  Description: The value to set for the option.

Code example:

Invoke the method:

$( ".selector" ).autocomplete( "option", "disabled", true );
    

• options
  Type: Object
  Description: The option-value pairs to set.

Code example:

Invoke the method:

$( ".selector" ).autocomplete( "option", { disabled: true } );
    

• value
  Type: String

Code example:

Invoke the search method:

$( ".selector" ).autocomplete( "search", "" );
    

• This method does not accept any arguments.

Code example:

Invoke the widget method:

$( ".selector" ).autocomplete( "widget" );
    

Note: At this time the<ul> element created must contain an <a> element for compatibility with the menu widget. See the example below.

• ul
  Type: jQuery
  Description: The newly created<li>element must be appended to the<ul>element.
• item
  Type: Object
  
  • label
    Type: String
    Description: The string to display for the entry.
  • item
    Type: String
    Description: The value inserted into the input when the entry is selected.

Code example:

Add the entry's value as<li>a data attribute on

_renderItem: function( ul, item ) {
  return $( "<li>" )
    .attr( "data-value", item.value )
    .append( $( "<a>" ).text( item.label ) )
    .appendTo( ul );
}
    

• ul
  Type: jQuery
  Description: An empty<ul>element to be used as the widget's menu.
• items
  Type: Array
  Description: An array of items that match the user's input. Each item is an object with alabelandvalueproperty.

Code example:

Add a CSS class name to the old menu items.

_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li:odd" ).addClass( "odd" );
}
    

• This method does not accept any arguments.

Code example:

The menu is always displayed as 500 pixels wide.

_resizeMenu: function() {
  this.menu.element.outerWidth( 500 );
}
    

• event
  Type: Event
• ui
  Type: Object
  • item
    Type: Object
    Description: The item selected from the menu, otherwise the property isnull。

Code example:

Initialize the autocomplete with the specified change callback:

$( ".selector" ).autocomplete({
  change: function( event, ui ) {}
});
    

Bind an event listener to the autocompletechange event:

$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object

Note:uiThe object is empty; it is included for consistency with other events.

Code example:

Initialize the autocomplete with the specified close callback:

$( ".selector" ).autocomplete({
  close: function( event, ui ) {}
});
    

Bind an event listener to the autocompleteclose event:

$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object

Note:uiThe object is empty; it is included for consistency with other events.

Code example:

Initialize the autocomplete with the specified create callback:

$( ".selector" ).autocomplete({
  create: function( event, ui ) {}
});
    

Bind an event listener to the autocompletecreate event:

$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object
  • item
    Type: Object
    Description: The item that gained focus.

Code example:

Initialize the autocomplete with the specified focus callback:

$( ".selector" ).autocomplete({
  focus: function( event, ui ) {}
});
    

Bind an event listener to the autocompletefocus event:

$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object

Note:uiThe object is empty; it is included for consistency with other events.

Code example:

Initialize the autocomplete with the specified open callback:

$( ".selector" ).autocomplete({
  open: function( event, ui ) {}
});
    

Bind an event listener to the autocompleteopen event:

$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object
  • content
    Type: Array
    Description: Contains the response data and can be modified to change the displayed results. This data is already normalized, so if you modify the data, make sure each item contains thevalueandlabelproperty.

Code examples:

Initialize autocomplete with the specified response callback:

$( ".selector" ).autocomplete({
  response: function( event, ui ) {}
});
    

Bind an event listener to the autocompleteresponse event:

$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object

Note:uiThe object is empty; it is included here for consistency with other events.

Code examples:

Initialize autocomplete with the specified search callback:

$( ".selector" ).autocomplete({
  search: function( event, ui ) {}
});
    

Bind an event listener to the autocompletesearch event:

$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
    

• event
  Type: Event
• ui
  Type: Object
  • item
    Type: Object
    Description: An object with the selected item'slabelandvalueproperties.

Code examples:

Initialize autocomplete with the specified select callback:

$( ".selector" ).autocomplete({
  select: function( event, ui ) {}
});
    

Bind an event listener to the autocompleteselect event:

$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );