Telerik UI for Windows 8 HTML

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


RadTokenInput can be bound to both local arrays and remote data via the underlying Telerik.Data.DataSource component; an abstraction for local and remote data.

The properties used to bind the dropdownlist are:

  • autoBind: A boolean property indicating whether the control should be bound to the data on initialization. Its default value is true.

  • dataSource: Specifies the object from which RadTokenInput will fetch its items.

  • dataTextField: Gets or sets the field from the dataSource which will be used to provide text for the RadTokenInput list items.

  • dataValueField: Gets or sets the field from the dataSource which will be used to populate the items value.

Below you can see examples of binding RadTokenInput to local and remote sources.

Local Sources

To bind RadDropDownList locally, you can set the dataSource property to a local array.

Binding to Local Sources Copy imageCopy
var dataSource = ["Item1", "Item2", "Item3"];
var tokenInput = new Telerik.UI.RadTokenInput(document.getElementById("localSourcesTokenInput"), {
    dataSource: {
        data: dataSource

Remote Sources

You can bind RadTokenInput to both the Telerik.Data.DataSource component and a WinJS.Binding.List. You can see examples below.

Binding to Telerik.Data.DataSource

The easiest way to bind a RadTokenInput 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 or from local files containing data in XML or JSON format.

JavaScript Copy imageCopy
var dataSourceTokenInputCtrl = new Telerik.UI.RadTokenInput(document.getElementById('dataSourceTokenInput'), {
    dataTextField: "ProductName",
    dataValueField: "ProductID",
    filter: "contains",
    dataSource: {
        transport: {
            read: {
                url: "",
                dataType: "json"

        schema: {
            data: "value"
        sort: { field: "ProductName", dir: "asc" },
        onerror: function (e) { debugger; }

Binding to WinJS.Binding.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 employeesSource = new WinJS.Binding.List();
    url: "$format=json",
}).then(function (result) {
    var employees = JSON.parse(result.response).value;
    employees.forEach(function (employee) {
            name: employee.FirstName + " " + employee.LastName,
            id: employee.EmployeeID
var listTokenInputCtrl = new Telerik.UI.RadTokenInput(document.getElementById('listTokenInput'), {
    dataSource: employeesSource,
    dataTextField: "name",
    dataValueField: "id"

Configuring Filtering

You can control when and how RadTokenInput will filter its 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 RadTokenInput 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). The default value of the property is "none".

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

  • minLength: The minimum number of characters that should be typed before RadTokenInput queries its data source. By setting a number, greater than 0 (default value), you can search on more specific criteria.

Note that if you do not specify filter options, RadTokenInput will display all its available suggestions on focus. If you set minLength or filter to values different than their defaults, the user would first need to type in text, before the RadTokenInput fetches suggestions.

Filtering Example Copy imageCopy
var filteredTokenInputCtrl = new Telerik.UI.RadTokenInput(document.getElementById("filteredTokenInput"), {
    dataSource: {
        data: dataSource
    filter: "contains",
    minLength: 2,
    ignoreCase: true,
    delay: 1000

Configuring Selection

You can easily limit the number of items that can be selected in RadTokenInput. Just set the maxSelectedItems property to an integer value. This way, once the maximum number of selected values is reached, the dropdown list with the suggestions will not be displayed anymore.

Limiting Selection Example Copy imageCopy
var selectionLimitTokenInputCtrl = new Telerik.UI.RadTokenInput(document.getElementById("selectionLimitTokenInput"), {
    dataSource: {
        data: dataSource
    maxSelectedItems: 2

Configuring Presentation

You can use the properties below to modify the way the user interacts with the RadTokenInput control:

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

  • height: Use this property to set the RadTokenInput'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. The default value of the property is true.

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

  • readonly: A Boolean value that determines whether RadTokenInput is read-only.

Customizing Tags and Items

RadTokenInput exposes two properties that allow you to provide templates for its tags and items—tagTemplate and itemTemplate. For more information and examples of their usage, go to: Item Template and Tag Template.