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">Emploee</div>
        <div class="dx-field-value" data-bind="dxLookup: { dataSource: employees, activeStateEnabled: enableActiveState }"></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);
employees = [
  "Bob",
  "John",
  "Frank",
  "Robert",
  "Paul",
  "Elizabeth",
  "Mary",
  "Michael",
  "George"
];

clickAction

An action performed when the widget is clicked.

Type: Action
Default Value: null

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">Emploee</div>
        <div class="dx-field-value" data-bind="dxLookup: { dataSource: employees, clickAction: processClick }"></div>
    </div>
</div>
processClick = function () {
  DevExpress.ui.notify("The widget has been clicked", "info", 1000);
};
employees = [
  "Bob",
  "John",
  "Frank",
  "Robert",
  "Paul",
  "Elizabeth",
];

dataSource

A data source used to fetch the lookup data.

Type: Object
Default Value: null

The default template of a data source item object may contain the following fields.

  • html - specifies html code inserted into the item element
  • text - specifies text inserted into the item element

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

Show Example:
jQuery
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Select item</div>
    <div class="dx-field-value" data-bind="dxLookup: { dataSource: lookupDataSource, valueExpr: 'ProductID', displayExpr: 'ProductName' }"></div>
  </div>
</div>
lookupDataSource = {
  load: function (loadOptions) {
    if (loadOptions.refresh) {
      return $.get('http://sampleservices.devexpress.com/api/Products', {
        categoryId: 1,
        skip: 0,
        take: 10,
        searchString: loadOptions.searchString || ''
      });
    }
  },
  lookup: function (key) {
    return key ? $.get('http://sampleservices.devexpress.com/api/Products/' + key.toString()) : null;
  }
};

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="lookup" data-bind="dxLookup: { dataSource: employees, displayExpr: 'name', disabled: lookupDisabled}"></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>
employees = [
    { id: 1, name: "Bob", hired: 2005 },
    { id: 2, name: "John", hired: 2007 },
    { id: 3, name: "Frank", hired: 2001 },
    { id: 4, name: "Robert", hired: 2007 },
    { id: 5, name: "Paul", hired: 2011 },
    { id: 6, name: "Elizabeth", hired: 2000 },
    { id: 7, name: "Mary", hired: 2002 },
    { id: 8, name: "Michael", hired: 2003 },
    { id: 9, name: "George", hired: 2002 },
    { id: 10, name: "Deborah", hired: 2000 },
    { id: 11, name: "Lisa", hired: 1999 },
    { id: 12, name: "Mark", hired: 2011 }
];
lookupDisabled = ko.observable(false);
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: employees, displayExpr: displayExprValue, valueExpr: 'id' }"></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 }"></div>
  </div>
</div>

fields = [ "id", "name", "hired" ];
displayExprValue = ko.observable(fields[0]);
employees = [
    { id:1, name: "Bob", hired: 2005 },
    { id:2, name: "John", hired: 2007 },
    { id:3, name: "Frank", hired: 2001 },
    { id:4, name: "Robert", hired: 2007 },
    { id:5, name: "Paul", hired: 2011 },
    { id:6, name: "Elizabeth", hired: 2000 },
    { id:7, name: "Mary", hired: 2002 },
    { id:8, name: "Michael", hired: 2003 },
    { id:9, name: "George", hired: 2002 },
    { id:10, name: "Deborah", hired: 2000 },
    { id:11, name: "Lisa", hired: 1999 },
    { id:12, name: "Mark", hired: 2011 }
];

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: employees, displayExpr: displayExprValue, valueExpr: 'id', displayValue: currentValue }"></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 }"></div>
  </div>
</div>

currentValue = ko.observable('none');
fields = ["id", "name", "hired"];
displayExprValue = ko.observable(fields[0]);
employees = [
    { id:1, name: "Bob", hired: 2005 },
    { id:2, name: "John", hired: 2007 },
    { id:3, name: "Frank", hired: 2001 },
    { id:4, name: "Robert", hired: 2007 },
    { id:5, name: "Paul", hired: 2011 },
    { id:6, name: "Elizabeth", hired: 2000 },
    { id:7, name: "Mary", hired: 2002 },
    { id:8, name: "Michael", hired: 2003 },
    { id:9, name: "George", hired: 2002 },
    { id:10, name: "Deborah", hired: 2000 },
    { id:11, name: "Lisa", hired: 1999 },
    { id:12, name: "Mark", hired: 2011 }
];

fullScreen

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

Type: Boolean
Default Value: false

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 + "%"; }).

minFilterLength

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

Type: Number
Default Value: 0

placeholder

The text displayed by the widget when nothing is selected.

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

searchEnabled

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

Type: Boolean
Default Value: true

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

title

The title of the lookup window.

Type: String
Default Value: ""

Show Example:
jQuery
<div class="lookup" data-bind="dxLookup: { dataSource: employees, 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>
employees = [
    { id: 1, name: "Bob", hired: 2005 },
    { id: 2, name: "John", hired: 2007 },
    { id: 3, name: "Frank", hired: 2001 },
    { id: 4, name: "Robert", hired: 2007 },
    { id: 5, name: "Paul", hired: 2011 },
    { id: 6, name: "Elizabeth", hired: 2000 },
    { id: 7, name: "Mary", hired: 2002 },
    { id: 8, name: "Michael", hired: 2003 },
    { id: 9, name: "George", hired: 2002 },
    { id: 10, name: "Deborah", hired: 2000 },
    { id: 11, name: "Lisa", hired: 1999 },
    { id: 12, name: "Mark", hired: 2011 }
];
lookupTitle = ko.observable("My lookup");
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">Emploee ID</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { dataSource: employees, displayExpr: 'id', valueExpr: 'name', value: emploeeName }"></div>
  </div>
    <div class="dx-field">
        <div style="width:60%;" class="dx-field-label">Emploee Name</div>
        <div style="width:auto;" class="dx-field-value" data-bind="text: emploeeName"></div>
    </div>
</div>
emploeeName = ko.observable("none");
employees = [
    { id:1, name: "Bob", hired: 2005 },
    { id:2, name: "John", hired: 2007 },
    { id:3, name: "Frank", hired: 2001 },
    { id:4, name: "Robert", hired: 2007 },
    { id:5, name: "Paul", hired: 2011 },
    { id:6, name: "Elizabeth", hired: 2000 },
    { id:7, name: "Mary", hired: 2002 },
    { id:8, name: "Michael", hired: 2003 },
    { id:9, name: "George", hired: 2002 },
    { id:10, name: "Deborah", hired: 2000 },
    { id:11, name: "Lisa", hired: 1999 },
    { id:12, name: "Mark", hired: 2011 }
];

valueChangeAction

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

Type: Action
Default Value: null

Show Example:
jQuery
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">Emploee</div>
        <div class="dx-field-value" data-bind="dxLookup: { dataSource: employees, valueChangeAction: processValueChange }"></div>
    </div>
</div>
processValueChange = function () {
  DevExpress.ui.notify("The widget value has been changed", "info", 1000);
};
employees = [
  "Bob",
  "John",
  "Frank",
  "Robert",
  "Paul",
  "Elizabeth",
];

valueExpr

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

Type: String
Default Value: null

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: employees, displayExpr: 'name', valueExpr: valueExprValue, value: currentValue }"></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 }"></div>
  </div>
</div>

currentValue = ko.observable("none");
fields = ["name", "id", "hired"];
valueExprValue = ko.observable(fields[0]);
employees = [
    { id:1, name: "Bob", hired: 2005 },
    { id:2, name: "John", hired: 2007 },
    { id:3, name: "Frank", hired: 2001 },
    { id:4, name: "Robert", hired: 2007 },
    { id:5, name: "Paul", hired: 2011 },
    { id:6, name: "Elizabeth", hired: 2000 },
    { id:7, name: "Mary", hired: 2002 },
    { id:8, name: "Michael", hired: 2003 },
    { id:9, name: "George", hired: 2002 },
    { id:10, name: "Deborah", hired: 2000 },
    { id:11, name: "Lisa", hired: 1999 },
    { id:12, name: "Mark", hired: 2011 }
];

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 + "%"; }).