Telerik UI for Windows 8 HTML

In this help article, you will learn how RadAutoCompleteBox can be populated with suggestions, how the search process can be configured and what options you have for defining the way the suggestions are shown to the user.

Providing Suggestions

To provide suggestions for RadAutoCompleteBox you can use data:

  • from a local array

  • from a remote data service

Locally defined values are best for small, fixed sets of suggestions. Remote suggestions should be used for larger data sets. When used with the DataSource component, filtering large remote data services can be pushed to the server as well, maximizing client-side performance.

The properties used to bind the autocomplete box are:

  • dataSource: Specifies the object from which RadAutoCompleteBox will fetch its results.

  • dataTextField: Gets or sets the field from the dataSource which will be used to provide text for the autocomplete suggestions.

Below you can see examples of providing suggestions from local and remote sources.

Local Sources

To configure and provide RadAutoCompleteBox suggestions locally, you can set the dataSource property to a local array.

JavaScript Copy imageCopy
var dataSource = ["Item1", "Item2", "Item3"];
var autocomplete = new Telerik.UI.RadAutoCompleteBox(document.getElementById("localSourcesAutoComplete"), {
    dataSource: dataSource

Remote Sources

Binding to DataSource

The easiest way to bind a RadAutoCompleteBox to remote suggestions is to use the DataSource component (Telerik.Data.DataSource) - an abstraction for local and remote data. The DataSource component can be used to serve data from XML and JSON data services.

JavaScript Copy imageCopy
var dataSourceAutoCompleteCtrl = new Telerik.UI.RadAutoCompleteBox(document.getElementById('dataSourceAutoComplete'), {
    minLength: 3,
    dataTextField: "ProductName",
    filter: "contains",
    dataSource: {
        transport: {
            read: {
                url: "",
                dataType: "json"

        schema: {
            data: "value"
        sort: { field: "ProductName", dir: "asc" }

Binding to List

Another option is to request the data manually through the WinJS.xhr function and populate the results in a WinJS.Binding.List object. An example is shown below:

JavaScript Copy imageCopy
var customersSource = new WinJS.Binding.List();
    url: "$format=json",
}).then(function (result) {
    var customers = JSON.parse(result.response).value;
    customers.forEach(function (customer) {
            name: customer.CompanyName

var listAutoCompleteCtrl = new Telerik.UI.RadAutoCompleteBox(document.getElementById('listAutoComplete'), {
    minLength: 2,
    dataSource: customersSource,
    dataTextField: "name"

Note that in the first scenario, the DataSource control is dynamically requesting the data, which is filtered remotely, based on the value of the autocomplete box. In the second scenario, the entire data is queried and populated into the List object and is then filtered by the autocomplete box.

Configuring the Search

You can control when and how RadAutoCompleteBox will perform a search for suggestions. The following properties help you achieve this:

  • delay: The delay in milliseconds after which the control will start filtering the dataSource. Using this property, you can postpone the filtering, allowing the user to type in more text before the autocomplete starts searching for suggestions.

  • filter: Sets the filter function used when filtering the data. The meaningful values that you can use are "eq" (equals), "contains" (contains) and "startswith" (starts with).

  • ignoreCase: A Boolean type property indicating whether or not search for suggestions should be case-sensitive.

  • minLength: The minimum number of characters that should be typed before RadAutoCompleteBox queries its data source. This way you can search on more specific criteria.

Filtering Example Copy imageCopy
var filteredAutoCompleteCtrl = new Telerik.UI.RadAutoCompleteBox(document.getElementById("filteredAutoComplete"), {
    dataSource: dataSource,
    filter: "endsWith",
    minLength: 1,
    ignoreCase: true,
    delay: 1000

Enabling Multiselection

You can allow the user to select multiple values. This is achieved through setting the separator property. By default, its value is empty and single selection is allowed. If you set it to a value different than empty string, on selecting an item, the specified separator will be appended to the text in the autocomplete box and the user can continue typing new search text.

The declaration below will result in the autocomplete adding a comma and a space after each selected suggestion:

Multiselection Copy imageCopy
var multiSelectionAutoCompleteCtrl = new Telerik.UI.RadAutoCompleteBox(document.getElementById("multiSelectionAutoComplete"), {
    dataSource: dataSource,
    filter: "endsWith",
    minLength: 1,
    ignoreCase: false,
    separator: ", "

Presenting the Suggestions

Based on your requirements, you can provide different settings for facilitating the user's selection of text. They include:

  • autoSuggest: Autocompletes the rest of the text in the text input area while the user is typing. The value used to complete the entry is the first one matching the current criteria.

    Auto suggest
  • height: Use this property to set the RadAutoCompleteBox's dropdown list height in pixels.

  • highlightFirst: A Boolean value indicating whether the first item should automatically be marked for selection. Pressing Enter while typing in this case will select the item.

    Highlight the first match
  • enabled: Gets or sets the enabled state of the control. You can use it when you want to prevent selecting a value in RadAutoCompleteBox, for example, if the user has to perform another action before being able to interact with the control.

  • placeholder: Allows you to specify text to display in the input area before the user starts typing.

    Showing empty text
  • readonly: Gets or sets whether the RadAutoCompleteBox is read-only.

  • text: You can use this property to get or set the text content of the control.

For example:

JavaScript Copy imageCopy
var customPresentingAutoCompleteCtrl = new Telerik.UI.RadAutoCompleteBox(document.getElementById("customPresentingAutoComplete"), {
    dataSource: dataSource,
    minLength: 1,
    autoSuggest: true,
    highlightFirst: true,
    placeholder: "Type text to search for..."

Focusing the control

Since Q2 2013, RadAutoCompleteBox exposes a focus() method. You can use it to programatically focus a control and allow the user to directly start typing in it.

See Also