Lookup Configuration

An object defining configuration options for the dxLookup 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.

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">State</div>
        <div class="dx-field-value" data-bind="dxLookup: {
            dataSource: lookupDataSource,
            displayExpr: 'name',
            activeStateEnabled: enableActiveState,
            title: 'States'
        }"></div>
    </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Active state</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: enableActiveState }"></div>
  </div>
</div>
enableActiveState = ko.observable(true);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

animation

An object defining widget animation options.

Type: animation configuration
Default Value: undefined

autoPagingEnabled

A Boolean value specifying whether or not to load the next page from the data source when the widget is scrolled to the bottom.

Type: Boolean
Default Value: true

You can also load the next page's data on the "More" button click. Assign true to the showNextButton option to display the "more" button.

cancelButtonText

The text displayed on the Cancel button.

Type: String
Default Value: "Cancel"

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showDoneButton: true,
    showCancelButton: true,
    showClearButton: true,
    doneButtonText: lookupDoneButtonText,
    cancelButtonText: lookupCancelButtonText,
    clearButtonText: lookupClearButtonText,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align:left;">
  <div class="dx-field">
    <p><b>Done Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupDoneButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Cancel Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupCancelButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Clear Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupClearButtonText }"></p>
  </div>
</div>
lookupDoneButtonText = ko.observable("Done");
lookupCancelButtonText = ko.observable("Cancel");
lookupClearButtonText = ko.observable("Clear");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

clearButtonText

The text displayed on the Clear button.

Type: String
Default Value: "Clear"

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showDoneButton: true,
    showCancelButton: true,
    showClearButton: true,
    doneButtonText: lookupDoneButtonText,
    cancelButtonText: lookupCancelButtonText,
    clearButtonText: lookupClearButtonText,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align:left;">
  <div class="dx-field">
    <p><b>Done Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupDoneButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Cancel Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupCancelButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Clear Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupClearButtonText }"></p>
  </div>
</div>
lookupDoneButtonText = ko.observable("Done");
lookupCancelButtonText = ko.observable("Cancel");
lookupClearButtonText = ko.observable("Clear");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

closeAction

An action performed after the lookup list has been hidden.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action after the lookup list has been hidden.

Alternatively, you can assign a URL to which the browser will navigate after the lookup list is hidden.

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">States</div>
        <div class="dx-field-value" data-bind="dxLookup: {
            dataSource: lookupDataSource,
            displayExpr: 'name',
            closeAction: processClosing,
            title: 'States'
        }"></div>
    </div>
</div>
processClosing = function () {
    DevExpress.ui.notify("The popup window has been hidden", "info", 1000);
};

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

closeOnOutsideClick

A Boolean value specifying whether or not the widget is closed if a user clicks outside of the overlaying window.

Type: Boolean|function
Return Value: Boolean
The required option value.
Default Value: false

contentReadyAction

An action performed when lookup list content is ready.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action when lookup list content is ready.

Alternatively, you can assign a URL to which the browser will navigate when the lookup list content is ready.

If data displayed by the widget is specified using a DataSource instance, the contentReadyAction is executed each time the load() method of the DataSource instance is called as well as when widget content is ready. In this case, when you create the widget, the contentReadyAction is executed twice: when widget content is ready (at this moment, the widget does not display items) and when the DataSource is loaded (the widget displays the loaded items).

dataSource

A data source used to fetch data to be displayed by the widget.

Default Value: null

You can assign an array directly to this option, as well as use the Data Source provided by DevExtreme.

If the dxLookup widget works with the data accessed via a DataSource instance wrapping a CustomStore, pay attention to the byKey option of the CustomStore instance, which is required for this widget. This option takes on a function used to get an item by a key.

To display widget items, a default template can be used. This template is based on the data source fields that are listed in the Default Item Template section of the widget's API. Alternatively, you can implement a custom item template. For details refer to the Customize Widget Item Appearance topic.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">State</div>
    <div class="dx-field-value" data-bind="dxLookup: { 
        dataSource: lookupDataSource,
        displayExpr: 'name',
        title: 'States'
    }"></div>
  </div>
</div>
//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

disabled

A Boolean value specifying whether or not the widget 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 widget at runtime.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: { 
    dataSource: lookupDataSource,
    displayExpr: 'name',
    disabled: lookupDisabled,
    title: 'States'
}"></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: lookupDisabled }"></div>
  </div>
</div>
lookupDisabled = ko.observable(false);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  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 Lookup 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 or path to the option.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Select item</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { 
        dataSource: lookupDataSource,
        displayExpr: displayExprValue,
        title: 'States'
    }"></div>
  </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: displayExprValue,
        title: 'Display Expr'
    }"></div>
  </div>
</div>

fields = ["name", "capital", "population", "area"];
displayExprValue = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

displayValue

Returns the value currently displayed by the widget.

Type: String
Default Value: undefined

The value you pass to this option does not affect widget behavior. Pass an observable variable to this option to get the value currently displayed by the widget.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Select item</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { 
        dataSource: lookupDataSource,
        displayExpr: displayExprValue,
        displayValue: currentValue,
        title: 'States'
    }"></div>
  </div>
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Current Value</div>
    <div style="width:auto;" class="dx-field-value" data-bind="text: currentValue"></div>
  </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: displayExprValue,
        title: 'Display Expr'
    }"></div>
  </div>
</div>

currentValue = ko.observable('none');
fields = ["name", "capital", "population", "area"];
displayExprValue = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

doneButtonText

The text displayed on the Done button.

Type: String
Default Value: "Done"

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showDoneButton: true,
    showCancelButton: true,
    showClearButton: true,
    doneButtonText: lookupDoneButtonText,
    cancelButtonText: lookupCancelButtonText,
    clearButtonText: lookupClearButtonText,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align:left;">
  <div class="dx-field">
    <p><b>Done Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupDoneButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Cancel Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupCancelButtonText }"></p>
  </div>
  <div class="dx-field">
    <p><b>Clear Button Text:</b></p>
    <p data-bind="dxTextBox: { value: lookupClearButtonText }"></p>
  </div>
</div>
lookupDoneButtonText = ko.observable("Done");
lookupCancelButtonText = ko.observable("Cancel");
lookupClearButtonText = ko.observable("Clear");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

fullScreen

A Boolean value specifying whether or not to display the lookup in full-screen mode.

Type: Boolean
Default Value: false
Default for windows phone 8: true
Default for iPhone: true

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: { 
    dataSource: lookupDataSource,
    displayExpr: 'name',
    fullScreen: lookupfullScreen,
    title: 'States'
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Full Screen</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: lookupfullScreen }"></div>
  </div>
</div>
lookupfullScreen = ko.observable(true);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}

grouped

A Boolean value specifying whether or not to group widget items.

Type: Boolean
Default Value: false

If this option is set to 'true', the object assigned to the items option should include key and items properties. The key property specifies the group caption in the list. The items property represents an array listing group items.

groupRender

A function rendering a group header.

Type: function
Function parameters:
itemData: Object
The data that is bound to the rendered group.
itemIndex: Number
The index of the group to be rendered.
itemElement: jQuery
An HTML element of the group to be rendered.
Return Value: String|DOM Node|jQuery
An HTML string, Element, or jQuery object representing the rendered group caption.
Default Value: null

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

  • groupData - the data source element representing the rendered group
  • groupIndex - the index of the rendered group
  • groupElement - the HTML element containing the rendered group

groupTemplate

The name of the template used to display a group header.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery
A template name or a template container.
Default Value: "group"

height

Specifies the height of the widget.

Type: Number|String|function
Return Value: Number|String
The widget height.
Default Value: undefined

The option can hold a value of the following types.

  • numeric
    The widget height in pixels.
  • string
    A CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit").
  • function
    The function returning the widget height. For example, see the following code.

    JavaScript
    height: function () { 
        return baseHeight - 10 + "%";
    }

hiddenAction

Deprecated

Use the closeAction option instead.

An action performed after the lookup list has been hidden.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action after the lookup list has been hidden.

Alternatively, you can assign a URL to which the browser will navigate after the lookup list is hidden.

hoverStateEnabled

A Boolean value specifying whether or not the widget changes its state when being hovered by an end user.

Type: Boolean
Default Value: true

itemRender

A function used to render collection items in the lookup list.

Type: function
Function parameters:
itemData: Object
The data that is bound to the rendered item.
itemIndex: Number
The index of the item to be rendered.
itemElement: jQuery
An HTML element of the item to be rendered.
Return Value: String|DOM Node|jQuery
An HTML string, Element, or jQuery object representing the rendered item.
Default Value: null

As in all container widgets in DevExtreme, lookup items are displayed by a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

Implement the itemRender function to provide a custom template for lookup items. This function is called each time a collection item of the widget is rendered. The following data is passed as function parameters.

  1. itemData - An object representing the rendered item.
  2. itemIndex - An index of the rendered item.
  3. itemElement - A container element containing the rendered item.

Return an HTML string, Element, or jQuery object representing the rendered item.

Alternatively, you can define the dxTemplate markup component within the widget element and set its option name to item. In this case, the markup enclosed in the dxTemplate component will automatically be applied as an item template. In addition, you may need to define several item templates and apply each of these when required. In this instance, use the itemTemplate option to set the required template.

Refer to the Customize Widget Item Appearance topic to learn more about ways to render collection items.

Show Example:
jQuery
 <div id="lookupContainer"></div>
//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

//A function used to render items
itemRenderer = function (itemData, itemIndex, itemElement) {
    var result = "<div style=\"display:inline-block; margin: 5px; text-align:left;\">\
    <img src=\"" + getImagePath(itemData.name) + "\"/>\
    </div>\
    <div style=\"display:inline-block; margin: 5px;\">\
    <p style=\"font-size:larger;\"><b>" + itemData.name + "</b></p>\
    Capital: <i>" + itemData.capital + "</i></p>\
    </div>";
    return result;
};

//Generates the path to the required image file
getImagePath = function (name) {
    if (name === undefined)
        return;
    return "/Content/images/doc/14_1/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};

$(function () {
    $("#lookupContainer").dxLookup({
        dataSource: lookupDataSource,
        displayExpr: "name",
        itemRender: itemRenderer,
        title: "States"
    })
});

body{
    text-align: left;
}
#lookupContainer{
    margin: 10px;
    text-align:center;
}

items

Specifies the array of items to be displayed by the widget.

Type: Array

Use this option instead of the dataSource option if you use a simple array as a data source.

itemTemplate

The template to be used for rendering items in the lookup list.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery
A template name or a template container.
Default Value: "item"

As in all container widgets in DevExtreme, lookup items are displayed by a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

In a simple case, you can define a single custom template for lookup items using the dxTemplate markup component within the widget's container. Set the name option of this component to 'item'. In this instance, this template will automatically be used as an item template, and you do not have to specify the itemTemplate option.

However, in some cases, you may need to have several custom item templates defined within the widget's container and apply each of them in different scenarios. In this instance, use one of the following ways to set the required template to the itemTemplate option.

  • Assign a string representing the name of the required template.
  • Assign a function that returns the name of the template as a result of a certain logic.

When you have several collection widgets, you may need to define a common template for them. For this purpose, factor out a template into a separate element, as demonstrated below.

HTML
<script type="text/html" id="person-template">
    <h3 data-bind="text: name"></h3>
    <p>Address: <span data-bind="text: address"></span></p>
</script>

To set the common template as a lookup item template, assign one of the following values to the itemTemplate option.

  • Assign a jQuery object representing the template's container
  • Assign a DOM Node representing the template's container
  • Assign a function that returns the jQuery object or a DOM Node representing the template's container
Show Example:
jQuery
<div data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',    
    itemTemplate: 'stateItem',
    title: 'States'
}">
  <div class="lookupItem" data-options="dxTemplate:{ name:'stateItem' }">
    <div style="display:inline-block; margin: 5px;">
      <img style="margin:5px;" data-bind="attr: { src: getImagePath(name) }" />
    </div>
    <div style="display:inline-block; margin: 5px;">
      <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 lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

//Generates the path to the required image file
getImagePath = function (name) {
    if (name === undefined)
        return;
    return "/Content/images/doc/14_1/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.lookupItem {
  text-align: left;
  padding: 5px;
}

minFilterLength

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

Type: Number
Default Value: 0

nextButtonText

The text displayed on the button used to load the next page from the data source.

Type: String
Default Value: "More"

noDataText

The text displayed by the widget if there are no items satisfying the specified search condition.

Type: String
Default Value: "No data to display"

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: [],
    noDataText: lookupNoDataText,
    title: 'Data'
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">NoDataText</div>
    <div class="dx-field-value" data-bind="dxTextBox: { value: lookupNoDataText }"></div>
  </div>
</div>
lookupNoDataText = ko.observable("No data to display");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

openAction

An action performed after the lookup list has been shown.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action after the lookup list has been shown.

Alternatively, you can assign a URL to which the browser will navigate after the lookup list is hidden.

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">State</div>
        <div class="dx-field-value" data-bind="dxLookup: {
            dataSource: lookupDataSource,
            displayExpr: 'name',
            openAction: processOpening,
            title: 'States'
        }"></div>
    </div>
</div>
processOpening = function () {
  DevExpress.ui.notify("The popup window has been shown", "info", 1000);
};

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

pageLoadingAction

An action performed before loading the next page in the lookup list if autopaging is enabled.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action before loading the next page.

Alternatively, you can assign a URL to which the browser will navigate before loading the next page.

pageLoadingText

Specifies the text shown in the pullDown panel, which is displayed when the widget is scrolled to the bottom.

Type: String
Default Value: "Loading..."

placeholder

The text displayed by the widget when nothing is selected.

Type: String
Default Value: "Select..."

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    placeholder: lookupPlaceholder,
    title: 'States'
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Placeholder</div>
    <div class="dx-field-value" data-bind="dxTextBox: { value: lookupPlaceholder }"></div>
  </div>
</div>
lookupPlaceholder = ko.observable("Select...");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

popupHeight

The height of the widget popup element.

Type: Number|String|function
Return Value: Number|String
The required height of the widget popup element.
Default Value: function() { return $(window).height() * 0.8 }
Default for iPad: function() { return Math.min($(window).width(), $(window).height()) * 0.4; },

Note that the option affects the actual popup size only if the fullScreen option is set to false. Otherwise, the popup is shown in a full screen mode.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Select item</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: {
        dataSource: lookupDataSource,
        displayExpr: displayExprValue,
        fullScreen: false,
        popupHeight: popupHeightValue,
        popupWidth: popupWidthValue,
        title: 'States'
    }"></div>
  </div>
</div>
<div class="dx-fieldset">
    <div class="dx-field">
        <p><b>popupWidth:</b> "<span data-bind="text: lookupWidth"></span>%"</p>
        <p data-bind="dxSlider: { min: 30, max: 100, value: lookupWidth }"></p>
    </div>
    <div class="dx-field">
        <p><b>popupHeight:</b> "<span data-bind="text: lookupHeight"></span>%"</p>
        <p data-bind="dxSlider: { min: 30, max: 100, value: lookupHeight }"></p>
    </div>
</div>

lookupWidth = ko.observable(70);
lookupHeight = ko.observable(70);
popupWidthValue = ko.observable("70%");
popupHeightValue = ko.observable("70%");
lookupWidth.subscribe(function (newValue) {
    popupWidthValue(newValue + "%");
});
lookupHeight.subscribe(function (newValue) {
    popupHeightValue(newValue + "%");
});

fields = ["name", "capital", "population", "area"];
displayExprValue = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

popupWidth

The width of the widget popup element.

Type: Number|String|function
Return Value: Number|String
The required width of the widget popup element.
Default Value: function() {return $(window).width() * 0.8 }
Default for iPad: function() { return Math.min($(window).width(), $(window).height()) * 0.4; }

Note that the option affects the actual popup size only if the fullScreen option is set to false. Otherwise, the popup is shown in a full screen mode.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Select item</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: {
        dataSource: lookupDataSource,
        displayExpr: displayExprValue,
        fullScreen: false,
        popupHeight: popupHeightValue,
        popupWidth: popupWidthValue,
        title: 'States'
    }"></div>
  </div>
</div>
<div class="dx-fieldset">
    <div class="dx-field">
        <p><b>popupWidth:</b> "<span data-bind="text: lookupWidth"></span>%"</p>
        <p data-bind="dxSlider: { min: 30, max: 100, value: lookupWidth }"></p>
    </div>
    <div class="dx-field">
        <p><b>popupHeight:</b> "<span data-bind="text: lookupHeight"></span>%"</p>
        <p data-bind="dxSlider: { min: 30, max: 100, value: lookupHeight }"></p>
    </div>
</div>

lookupWidth = ko.observable(70);
lookupHeight = ko.observable(70);
popupWidthValue = ko.observable("70%");
popupHeightValue = ko.observable("70%");
lookupWidth.subscribe(function (newValue) {
    popupWidthValue(newValue + "%");
});
lookupHeight.subscribe(function (newValue) {
    popupHeightValue(newValue + "%");
});

fields = ["name", "capital", "population", "area"];
displayExprValue = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

position

An object defining widget positioning options.

Type: Object
Default Value: undefined

pulledDownText

Specifies the text displayed in the pullDown panel when the widget is pulled below the refresh threshold.

Type: String
Default Value: "Release to refresh..."

pullingDownText

Specifies the text shown in the pullDown panel while the list is being pulled down to the refresh threshold.

Type: String
Default Value: "Pull down to refresh..."

pullRefreshAction

An action performed before the lookup list is refreshed as a result of the "pull down to refresh" gesture.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action before the lookup list is refreshed as a result of the "pull down to refresh" gesture.

Alternatively, you can assign a URL to which the browser will navigate before the lookup list is refreshed as a result of the "pull down to refresh" gesture.

pullRefreshEnabled

A Boolean value specifying whether or not the widget supports the "pull down to refresh" gesture.

Type: Boolean
Default Value: false

If the option is set to true, the widget data is refreshed each time you pull down and release widget contents.

NOTE: The "pull down to refresh" gesture is not supported by desktop browsers and Windows Phone devices. You can use it only in mobile themes except the Windows Phone theme.

refreshingText

Specifies the text displayed in the pullDown panel while the widget is being refreshed.

Type: String
Default Value: "Refreshing..."

rtlEnabled

Specifies whether or not the current component supports a right-to-left representation.

Type: Boolean
Default Value: false

If you need to switch the display of this DevExtreme component to right-to-left, enable a specifically designed configuration option - rtlEnabled. When this option is set to true, the text flows from right to left, and the layout the component's elements is reversed. To switch the entire application/site to a right-to-left representation, use the static DevExpress.rtlEnabled field.

scrollAction

An action performed on each scroll gesture in the lookup list.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
jQueryEvent: jQuery.Event
Specifies the jQuery event that caused the action's execution.
scrollOffset: Object
Returns the current scroll offset in the following format { top: topOffset, left: leftOffset }.
reachedLeft: Boolean
Indicates whether the container's left boundary is reached.
reachedRight: Boolean
Indicates whether the container's right boundary is reached
reachedTop: Boolean
Indicates whether the container's top boundary is reached.
reachedBottom: Boolean
Indicates whether the container's bottom boundary is reached.
Default Value: null

Assign a function to perform a custom action on each scroll gesture.

Alternatively, you can assign a URL to which the browser will navigate on each scroll gesture.

searchEnabled

A Boolean value specifying whether or not the search bar is visible.

Type: Boolean
Default Value: true

To specify a field by which to search items, assign the required field name to the searchExpr configuration option of the DataSource object passed to the dataSource option of the widget.

JavaScript
var dataSource = new DevExpress.data.DataSource({
    store: myStore,
    searchExpr: "firstName"
});

If you need to search items by several field values, assign an array of field names to the searchExpr option of the DataSource.

JavaScript
var dataSource = new DevExpress.data.DataSource({
    store: myStore,
    searchExpr: ["firstName", "lastName"]
});

For more information on searching, refer to the Search Api section of the Data Layer article.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    searchEnabled: enableSearch,
    title: 'States'
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label" style="width:70%">Search Enabled</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: enableSearch }"></div>
  </div>
</div>
enableSearch = ko.observable(true);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

searchPlaceholder

The text that is provided as a hint in the lookup's search bar.

Type: String
Default Value: "Search"

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    searchPlaceholder: placeholder,
    title: 'States'
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Search placeholder</div>
    <div class="dx-field-value" data-bind="dxTextBox: { value: placeholder }"></div>
  </div>
</div>
placeholder = ko.observable("Type here");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

searchTimeout

Specifies the time delay, in milliseconds, after the last character has been typed in, before a search is executed.

Type: Number
Default Value: 1000

shading

A Boolean value specifying whether or not the main screen is inactive while the lookup is active.

Type: Boolean
Default Value: true

showCancelButton

Specifies whether to display the Cancel button in the lookup window.

Type: Boolean
Default Value: true
Default for windows phone 8: false

The Cancel button cancels the attempt to change the lookup widget value.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showCancelButton: showCancel,
    showClearButton: showClear,
    showDoneButton: showDone,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align: left;">
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Cancel button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showCancel }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Clear button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showClear }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Done button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showDone }"></div>
    </div>
</div>
showCancel = ko.observable(true);
showClear = ko.observable(false);
showDone = ko.observable(false);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

showClearButton

Specifies whether or not to display the Clear button in the lookup window.

Type: Boolean
Default Value: false

The Clear button clears the currently chosen lookup value. The lookup window closes and the text specified by the placeholder option is shown in the lookup editor.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showCancelButton: showCancel,
    showClearButton: showClear,
    showDoneButton: showDone,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align: left;">
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Cancel button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showCancel }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Clear button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showClear }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Done button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showDone }"></div>
    </div>
</div>
showCancel = ko.observable(true);
showClear = ko.observable(false);
showDone = ko.observable(false);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

showDoneButton

Specifies whether to display the Done button in the lookup window.

Type: Boolean
Default Value: false

The Done button submits the selection in the lookup window.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: {
    dataSource: lookupDataSource,
    displayExpr: 'name',
    showCancelButton: showCancel,
    showClearButton: showClear,
    showDoneButton: showDone,
    title: 'States'
}"></div>
<div class="dx-fieldset" style="text-align: left;">
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Cancel button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showCancel }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Clear button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showClear }"></div>
    </div>
    <div class="dx-field">
        <div class="dx-field-label" style="width:70%;">Show Done button</div>
        <div class="dx-field-value" data-bind="dxCheckBox: { checked: showDone }"></div>
    </div>
</div>
showCancel = ko.observable(true);
showClear = ko.observable(false);
showDone = ko.observable(false);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

shownAction

Deprecated

Use the openAction option instead.

An action performed after the lookup list has been shown.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
Default Value: null

Assign a function to perform a custom action after the lookup list has been shown.

Alternatively, you can assign a URL to which the browser will navigate after the lookup list is hidden.

showNextButton

A Boolean value specifying whether the widget loads the next page automatically when you reach the bottom of the list or when a button is clicked.

Type: Boolean
Default Value: false

If this option is set to true, the widget shows a "Next Page" button, and loads the next page of data when you click this button. Otherwise, the widget loads the data automatically each time you reach the bottom of the list.

NOTE: The default value of this option is false if your application is running on a mobile platform. If you run the application on the desktop, the default value is true.

title

The title of the lookup window.

Type: String
Default Value: ""

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: { dataSource: lookupDataSource, displayExpr: 'name', title: lookupTitle }"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Title</div>
    <div class="dx-field-value" data-bind="dxTextBox: { value: lookupTitle }"></div>
  </div>
</div>
lookupTitle = ko.observable("Select state");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

titleTemplate

A template to be used for rendering the widget title.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery
A template name or a template container.
Default Value: "title"

This option enables you to render the widget title depending on field values of the bound data model.

HTML
<div data-options="dxTemplate: { name:'myTitle' }">
    <h3><span data-bind="text: $data.fullName"></span> info</h3>
</div>

The $data variable, available within the template, contains the data model object bound to the current view.

useNativeScrolling

Specifies whether or not the widget uses native scrolling.

Type: Boolean
Default Value: true
Default for android below version 4: false
Default for tizen: false

usePopover

Specifies whether or not to show lookup contents in a dxPopover widget.

Type: Boolean
Default Value: false

The dxLookup widget can display its contents in a dxPopover widget only if the fullScreen mode is disabled. Otherwise, lookup contents are displayed within the dxPopup widget.

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: { 
    dataSource: lookupDataSource,
    displayExpr: 'name',
    title: 'Select value',
    usePopover: showAsPopover,
    fullScreen: false
}"></div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Use Popover</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: showAsPopover }"></div>
  </div>
</div>
showAsPopover = ko.observable(false);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");
body{
  text-align: center;
}
.lookup{
  margin: 10px;
}

value

The currently selected value in the widget.

Type: Object
Default Value: undefined

This option returns a value of the specified field of the currently selected item object. The field whose value is returned by the value option is specified via the valueExpr option.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">State</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: {
        dataSource: lookupDataSource,
        displayExpr: 'name',
        valueExpr: 'capital',
        value: capital,
        title: 'States'
    }"></div>
  </div>
    <div class="dx-field">
        <div style="width:60%;" class="dx-field-label">Capital</div>
        <div style="width:auto;" class="dx-field-value" data-bind="text: capital"></div>
    </div>
</div>
capital = ko.observable("none");

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

valueChangeAction

An action performed after the value of the widget has been changed.

Type: String|function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element.
value: Object
Returns the widget's new value.
previousValue: Object
Returns the widget's previous value.
selectedItem: Object
Returns the widget's selected item.
jQueryEvent: jQuery.Event
Specifies the jQuery event that caused the action's execution.
Default Value: null

Assign a function to perform a custom action after the value of the widget is changed.

Alternatively, you can assign a URL to which the browser will navigate after the value of the widget is changed.

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">States</div>
        <div class="dx-field-value" data-bind="dxLookup: {
            dataSource: lookupDataSource,
            displayExpr: 'name',
            valueChangeAction: processValueChange,
            title: 'States'
        }"></div>
    </div>
</div>
processValueChange = function () {
  DevExpress.ui.notify("The widget value has been changed", "info", 1000);
};

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

valueExpr

Specifies the name of a data source item field whose value is held in the value configuration option.

Type: String
Default Value: null

If you leave the option unassigned, the value option holds the entire dataSource item corresponding to the selected value.

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">Select item</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: {
        dataSource: lookupDataSource,
        displayExpr: 'name',
        valueExpr: valueExprValue,
        value: currentValue,
        title: 'States'
    }"></div>
  </div>
    <div class="dx-field">
        <div style="width:60%;" class="dx-field-label">Value</div>
        <div style="width:auto;" class="dx-field-value" data-bind="text: currentValue"></div>
    </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">valueExpr</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { 
        dataSource: fields,
        value: valueExprValue,
        title: 'Value Expr'
    }"></div>
  </div>
</div>
currentValue = ko.observable("none");
fields = ["this", "name", "capital", "population", "area"];
valueExprValue = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the lookup
lookupDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        lookupDataSource.store().insert(data[i]);
    }
    lookupDataSource.load();
}, "json");

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
Return Value: Number|String
The widget width.
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. For example, see the following code.

    JavaScript
    width: function () { 
        return baseWidth - 10 + "%";
    }