kendo.ui.AutoComplete
Edit this docRepresents the Kendo UI AutoComplete widget. Inherits from Widget.
Important: The Kendo UI AutoComplete should be created from an input HTML element.
No results. Try clearing the filter.
Configures the opening and closing animations of the suggestion popup. Setting the animation option to false will disable the opening and closing animations. As a result the suggestion popup will open and close instantly.
Example - disable open and close animations
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
animation: false
});
</script>
Example - configure the animation
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
animation: {
close: {
effects: "fadeOut zoom:out",
duration: 300
},
open: {
effects: "fadeIn zoom:in",
duration: 300
}
}
});
</script>
The animation played when the suggestion popup is closed.
Example - configure the close animation
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
animation: {
close: {
effects: "fadeOut zoom:out",
duration: 300
}
}
});
</script>
The duration of the close animation in milliseconds.
The animation played when the suggestion popup is opened.
Example - configure the open animation
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
animation: {
open: {
effects: "fadeIn zoom:in",
duration: 300
}
}
});
</script>
The duration of the open animation in milliseconds.
The data source of the widget which is used to display suggestions for the current value. Can be a JavaScript object which represents a valid data source configuration, a JavaScript array or an existing kendo.data.DataSource
instance.
If the dataSource option is set to a JavaScript object or array the widget will initialize a new kendo.data.DataSource instance using that value as data source configuration.
If the dataSource option is an existing kendo.data.DataSource instance the widget will use that instance and will not initialize a new one.
Example - set dataSource as a JavaScript object
<input id="autocomplete" />
<script>
$("#autoComplete").kendoAutoComplete({
dataSource: {
data: ["One", "Two"]
}
});
</script>
Example - set dataSource as a JavaScript array
<input id="autocomplete" />
<script>
var data = ["One", "Two"];
$("#autoComplete").kendoAutoComplete({
dataSource: data
});
</script>
Example - set dataSource as an existing kendo.data.DataSource instance
<input id="autocomplete" />
<script>
var dataSource = new kendo.data.DataSource({
transport: {
read: {
url: "http://demos.kendoui.com/service/products",
dataType: "jsonp"
}
}
});
$("#autocomplete").kendoAutoComplete({
dataSource: dataSource,
dataTextField: "ProductName"
});
</script>
The field of the data item used when searching for suggestions. This is the text that will be displayed in the list of matched results.
Example - set the dataTextField
<input id="autocomplete" />
<script>
var data = [
{ id: 1, name: "Apples" },
{ id: 2, name: "Oranges" }
];
$("#autocomplete").kendoAutoComplete({
dataTextField: "name", // The widget is bound to the "name" field
dataSource: data
});
</script>
The delay in milliseconds between a keystroke and when the widget displays the suggestion popup.
Example - set the delay
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
delay: 500
});
</script>
If set to false the widget will be disabled and will not allow user input. The widget is enabled by default and allows user input.
Example - disable the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
enable: false
});
</script>
The filtering method used to determine the suggestions for the current value. The default filter is "startswith" -
all data items which begin with the current widget value are displayed in the suggestion popup. The supported filter values are startswith, endswith and contains.
Example - set the filter
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
filter: "contains"
});
</script>
The height of the suggestion popup in pixels. The default value is 200 pixels.
Example - set the height
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
height: 500
});
</script>
If set to true the first suggestion will be automatically highlighted.
Example - set highlightFirst
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
highlightFirst: false
});
</script>
If set to false case-sensitive search will be performed to find suggestions. The widget performs case-insensitive searching by default.
Example - disable case-insensitive suggestions
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
ignoreCase: false
});
</script>
The minimum number of characters the user must type before a search is performed. Set to higher value than 1 if the search could match a lot of items.
Example - set minLength
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
minLength: 3
});
</script>
The hint displayed by the widget when it is empty. Not set by default.
Example - specify placeholder
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
placeholder: "Enter value ..."
});
</script>
The Kendo UI AutoComplete widget could also use the value of the placeholder HTML attribute as hint.
Example - use the placeholder HTML attribute
<input id="autocomplete" placeholder="Enter value..." />
<script>
$("#autocomplete").kendoAutoComplete();
</script>
The character used to separate multiple values. Empty by default.
Example - set separator to allow multiple values
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
separator: ", "
});
</script>
If set to true the widget will automatically use the first suggestion as its value.
Example - enable automatic suggestion
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
suggest: true
});
</script>
The template used to render the suggestions. By default the widget displays only the text of the suggestion (configured via dataTextField).
Example - specify template as a function
<input id="autocomplete" />
<script id="template" type="text/x-kendo-template">
<span>
<img src="/img/#: id #.png" alt="#: name #" />
#: name #
</span>
</script>
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [
{ id: 1, name: "Apples" },
{ id: 2, name: "Oranges" }
],
dataTextField: "name",
template: kendo.template($("#template").html())
});
</script>
Example - specify template as a string
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [
{ id: 1, name: "Apples" },
{ id: 2, name: "Oranges" }
],
dataTextField: "name",
template: '<span><img src="/img/#: id #.png" alt="#: name #" />#: name #</span>'
});
</script>
The data source of the widget. Configured via the dataSource option.
Changes of the data source will be reflected in the widget.
Important: Assigning a new data source would have no effect. Use the setDataSource method instead.
Example - add a data item to the data source
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [
{ name: "Apples" },
{ name: "Oranges" }
],
dataTextField: "name"
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.dataSource.read();
autocomplete.dataSource.add({ name: "Appricot" });
autocomplete.search("A");
</script>
Closes the widget suggestion popup.
Example - close the suggestion popup
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
// Search for items starting with "A" - will open the suggestion popup and show "Apples"
autocomplete.search("A");
// Close the suggestion popup
autocomplete.close();
</script>
Returns the data item at the specified index.
Parameters
- index
Number(optional) The zero-based index of of the data item.
Returns
Object the data item at the specified index. Returns undefined if the index is not within bounds.
Example - get the item at certain index
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
// Search for items starting with "A" - will open the suggestion popup and show "Apples"
autocomplete.search("A");
console.log(autocomplete.dataItem(0)); // Displays "Apples" in the browser console
</script>
Prepares the widget for safe removal from DOM. Detaches all event handlers and removes jQuery.data attributes to avoid memory leaks. Calls destroy method of any child Kendo widgets.
Important: This method does not remove the widget element from DOM.
Example
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.destroy();
</script>
Enables or disables the widget.
Parameters
- enable
Boolean If set to true the widget will be enabled. If set to false the widget will be disabled.
Example - enable the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
enable: false
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.enable(true);
</script>
Example - disable the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.enable(false);
</script>
Toggles the readonly state of the widget. When the widget is readonly it doesn't allow user input.
There is a difference between disabled and readonly mode. The value of a disabled widget is not posted as part of a form whereas the value of a readonly widget is posted.
Parameters
- readonly
Boolean If set to true the widget will not allow user input. If set to false the widget will allow user input.
Example - make the widget readonly
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.readonly(true);
</script>
Focuses the widget.
Example - focus the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.focus();
</script>
Refresh the suggestion popup by rendering all items again.
Example - refresh the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.refresh();
</script>
Searches the data source for the provided value and displays any matches as suggestions.
Parameters
- word
String The value to search for. All matches are displayed in the suggestion popup.
Example - search the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.search("A"); // Displays "Apples" in the suggestion popup
</script>
Selects the item provided as an argument and updates the value of the widget.
Parameters
- item
String|Element|jQuery A string, DOM element or jQuery object which represents the item to be selected. A string is treated as a jQuery selector.
Example - select item
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "John", "Jane" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.search("J");
autocomplete.select(autocomplete.ul.children().eq(1)); // Selects the second suggestion which is "Jane"
</script>
Sets the data source of the widget.
Parameters
- dataSource
kendo.data.DataSource The data source to which the widget should be bound.
Example
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var dataSource = new kendo.data.DataSource({
data: [ "Bananas", "Cherries" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.setDataSource(dataSource);
</script>
Sets the value of the widget to the specified argument and visually selects the text.
Parameters
- value
String The value to set.
Example
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.suggest("Apples");
</script>
Gets or sets the value of the widget.
Parameters
- value
String The value to set.
Returns
String the value of the widget.
Example - set and get the value of the widget
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataSource: [ "Apples", "Oranges" ]
});
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.value("Apples");
var value = autocomplete.value();
console.log(value); // Displays "Apples"
</script>
Fired when the value of the widget is changed by the user.
The event handler function context (available via the this keyword) will be set to the widget instance.
Important: The event is not fired when the value of the widget is changed from code.
Event Data
- e.sender
kendo.ui.AutoComplete The widget instance which fired the event.
Example - subscribe to the "change" event during initialization
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
change: function(e) {
var value = this.value();
// Use the value of the widget
}
});
</script>
Example - subscribe to the "change" event after initialization
<input id="autocomplete" />
<script>
function autocomplete_change(e) {
var value = this.value();
// Use the value of the widget
}
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.bind("change", autocomplete_change);
</script>
Fired when the suggestion popup of the widget is closed by the user.
The event handler function context (available via the this keyword) will be set to the widget instance.
Event Data
- e.sender
kendo.ui.AutoComplete The widget instance which fired the event.
Example - subscribe to the "close" event during initialization
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
close: function(e) {
// handle the event
}
});
</script>
Example - subscribe to the "close" event after initialization
<input id="autocomplete" />
<script>
function autocomplete_close(e) {
// handle the event
}
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.bind("close", autocomplete_close);
</script>
Fired when the widget is bound to data from its data source.
The event handler function context (available via the this keyword) will be set to the widget instance.
Event Data
- e.sender
kendo.ui.AutoComplete The widget instance which fired the event.
Example - subscribe to the "dataBound" event during initialization
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
dataBound: function(e) {
// handle the event
}
});
</script>
Example - subscribe to the "dataBound" event after initialization
<input id="autocomplete" />
<script>
function autocomplete_dataBound(e) {
// handle the event
}
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.bind("dataBound", autocomplete_dataBound);
</script>
Fired when the suggestion popup of the widget is opened by the user.
The event handler function context (available via the this keyword) will be set to the widget instance.
Event Data
- e.sender
kendo.ui.AutoComplete The widget instance which fired the event.
Example - subscribe to the "open" event during initialization
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
open: function(e) {
// handle the event
}
});
</script>
Example - subscribe to the "open" event after initialization
<input id="autocomplete" />
<script>
function autocomplete_open(e) {
// handle the event
}
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.bind("open", autocomplete_open);
</script>
Fired when an item from the suggestion popup is selected by the user.
Event Data
- e.item
jQuery The jQuery object which represents the selected item.
- e.sender
kendo.ui.AutoComplete The widget instance which fired the event.
Example - subscribe to the "select" event during initialization
<input id="autocomplete" />
<script>
$("#autocomplete").kendoAutoComplete({
select: function(e) {
var item = e.item;
var text = item.text();
// Use the selected item or its text
}
});
</script>
Example - subscribe to the "select" event after initialization
<input id="autocomplete" />
<script>
function autocomplete_select(e) {
var item = e.item;
var text = item.text();
// Use the selected item or its text
}
$("#autocomplete").kendoAutoComplete();
var autocomplete = $("#autocomplete").data("kendoAutoComplete");
autocomplete.bind("select", autocomplete_select);
</script>
A jQuery object of the original input element.
An object, which holds the options of the widget.
A jQuery object of the span element which wraps the input.
A jQuery object of the drop-down list element.
A jQuery object of the ul element, which holds the available options.
The DataSource instance used by the widget.
The Popup instace used by the widget.