Autocomplete Configuration

An object defining configuration options for the dxAutocomplete widget.

activeStateEnabled

A Boolean value specifying whether or not the widget changes its state when interacting with a user.

Type: Boolean
Default Value: true

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

clickAction

An action performed when the widget is clicked.

Type: Action
Default Value: null

Show Example:
jQuery
 <div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  clickAction: processClick,
  displayExpr: 'name',
  placeholder: 'Click here'
}">
  <div style="text-align: left;" data-options="dxTemplate: {name: 'item'}">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
processClick = function () {
  DevExpress.ui.dialog.alert("The widget has been clicked", "Action executed");
};

//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

dataSource

A data source used to fetch data for autocomplete.

Type: Object
Default Value: null

Refer to the Data-Bound Application tutorial for more information.

Show Example:
jQuery
 <div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  displayExpr: 'name',
  placeholder: 'Type a state name'
}">
   <div style="text-align: left;" data-options="dxTemplate: {name: 'item'}">
     <b data-bind="text:name"></b><br />
     <span style="color:grey;">Capital: <span data-bind="text: capital"></span></span>
   </div>
 </div>
//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

disabled

A Boolean value specifying whether or not a component can respond to user interaction.

Type: Boolean
Default Value: false

Create an observable variable and assign it to this option to specify the availability of the component at runtime.

Show Example:
jQuery
<div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  disabled: autocompleteDisabled,
  displayExpr: 'name',
  placeholder: 'Type a state name'
}">
  <div style="text-align: left;" data-options="dxTemplate: {name: 'item'}">
    <b data-bind="text: name"></b><br />
    <span style="color:grey;">Capital: <span data-bind="text: capital"></span></span>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Disabled</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: autocompleteDisabled }"></div>
  </div>
</div>
autocompleteDisabled = ko.observable(false);

//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

displayExpr

Specifies the name of the data source item field whose value is displayed by the widget.

Type: String
Default Value: "this"

If the Autocomplete item is a simple object holding a value (string, numeric, Boolean, etc.), assign 'this' to the displayExpr option. If the item is a plain object item, assign the required field name to the option.

Show Example:
jQuery
 <div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  displayExpr: currentDisplayExpr,
  placeholder: 'Type here'
}">
  <div data-options="dxTemplate: {name: 'item'}">
    <b data-bind="text:name"></b><br />
    <span style="color:grey;">Capital: <span data-bind="text: capital"></span></span>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">displayExpr</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { dataSource: fields, value: currentDisplayExpr }"></div>
  </div>
</div>
fields = ["name", "capital"];
currentDisplayExpr = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

height

Specifies the height of the widget.

Type: Number|String|function
Default Value: undefined

The option can hold a value of the following types:

  • numeric - the height of the widget in pixels;
  • string - a CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit");
  • function - a function returning the widget height (e.g., height:function(){ return baseHeight - 10 + "%"; }).

itemRender

A function used to render autocomplete items.

Type: function
Default Value: null

The rendering function should have the following parameters and return an HTML string, element, or jQuery object representing the rendered item.

  • itemData - the object representing the rendered item
  • itemIndex - the index of the rendered item
  • itemElement - the container element containing the rendered item

This option is useful if you work with widgets using jQuery. If you use Knockout, use the itemTemplate option to specify the appearance of autocomplete items.

Show Example:
jQuery
 <div id="autocompleteContainer"></div>
var searchStr;

//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    searchStr = loadOptions.searchString === undefined ? undefined : loadOptions.searchString.toLowerCase();
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});

//A function used to render items
itemRenderer = function (itemData, itemIndex, itemElement) {
  var result = "<b>";
  var nameLower = itemData.name.toLowerCase();
  if (searchStr === undefined)
    result+=itemData.name;
  else
    for (var i = 0; i < itemData.name.length; i++) {
      if (nameLower.substring(i, i+searchStr.length) !== searchStr) {
        result+=itemData.name[i];
        continue;
      }
      result += "<span style=\"color:red;\">" + itemData.name.substring(i, i + searchStr.length) + "</span>";
      i += searchStr.length - 1;
    }
  result += "</b><br />";
  result += "<span style=\"color:grey;\">Capital: " + itemData.capital + "</span>";
  return result;
};

$(function () {
  $("#autocompleteContainer").dxAutocomplete({
    dataSource: autocompleteDataSource,
    itemRender: itemRenderer,
    displayExpr: 'name',
    placeholder: 'Type state name'
  })
});
body{
  text-align: center;
}
#autocompleteContainer{
  margin: 10px;
}

itemTemplate

The name of the template used to render autocomplete items or the function returning the template name.

Type: String|function
Default Value: "item"

For more information on templates, see the dxTemplate description.

This option is only applicable if you use Knockout. Otherwise use the itemRender option to specify the appearance of autocomplete items.

Show Example:
jQuery
<div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  itemTemplate: 'myTemplate',
  displayExpr: 'name',
  placeholder: 'Type state name'
}">
  <div style="text-align: left;" data-options="dxTemplate: {name: 'myTemplate'}">
    <div style="display:inline-block">
      <img style="margin:5px;" data-bind="attr: { src: getImagePath(name) }" />
    </div>
    <div style="display:inline-block">
      <p style="font-size:larger;"><b data-bind="text: name"></b></p>
      <p>Capital: <i data-bind="text: capital"></i></p>
    </div>
  </div>
</div>
//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});

//Generates the path to the required image file
getImagePath = function (name) {
  if (name !== undefined)
    return "/Content/images/doc/13_1/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

minSearchLength

The minimum number of characters that must be entered into the search box to begin a search.

Type: Number
Default Value: 1

placeholder

The text displayed by the widget when the widget value is empty.

Type: String
Default Value: ""

searchTimeout

Specifies the time period in milliseconds before a search is executed.

Type: Number
Default Value: 0

value

Specifies the current value displayed by autocomplete.

Type: String
Default Value: ""

Show Example:
jQuery
<div class="autocomplete" data-bind="dxAutocomplete: {
  dataSource: autocompleteDataSource,
  displayExpr: 'name',
  placeholder: 'Type state name',
  value: autocompleteValue
}">
  <div style="text-align: left;" data-options="dxTemplate: {name: 'item'}">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">Value</div>
        <div class="dx-field-value" data-bind="dxTextBox: { value: autocompleteValue }"></div>
    </div>
</div>
autocompleteValue = ko.observable("");

//An object passed to the dataSource configuration option of the widget
autocompleteDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  }
});
body{
  text-align: center;
}
.autocomplete{
  margin: 10px;
}

visible

A Boolean value specifying whether or not the widget is visible.

Type: Boolean
Default Value: true

width

Specifies the width of the widget.

Type: Number|String|function
Default Value: undefined

The option can hold a value of the following types:

  • numeric - the widget width in pixels;
  • string - a CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit");
  • function - the function returning the widget width (e.g., width:function(){ return baseWidth - 10 + "%"; }).