Specifies options of a lookup column.

Type: Object
Default Value: undefined

Use a lookup column if you need to restrict the set of values that can be chosen when a user edits or filters a grid column. In a lookup column, each cell is a drop-down menu where items represent available values. Additionally, you can use a lookup column when you need to substitute displayed values for required values.

For example, consider that you have two arrays of objects: Drivers and Buses.

var drivers = [
    { DriverID: 1, FirstName: 'John', LastName: 'Smith', BusID: 2 },
    { DriverID: 2, FirstName: 'Lizzy', LastName: 'Cook', BusID: 1 },
    { DriverID: 3, FirstName: 'Brian', LastName: 'Hawkins', BusID: 3 }

var buses = [
    { BusID: 1, Plates: '123456' },
    { BusID: 2, Plates: 'AB-1234'  },
    { BusID: 3, Plates: 'CD-9876' }

The objects of the Drivers array have the BusID field, which binds these two arrays together. If the Drivers array takes on the role of the main grid data source, the BusID grid column displays the IDs of buses, which do not matter to a user. In this situation, it will be more convenient to display the bus license plates specified in the Plates field. For this purpose, the Buses array must be set as a lookup data source for the BusID grid column using the lookup | dataSource option. Then, the valueExpr option must be set to "BusID" indicating the field whose values should be replaced. These values will be replaced by the values of the field specified by the displayExpr option.

$(function () {
        dataSource: drivers,
        // ...
        columns: [
            // ...
            { dataField: 'BusID', lookup: { dataSource: buses, valueExpr: 'BusID', displayExpr: 'Plates' } },
            // ...

With this code applied, the "BusID" grid column contains the bus license plates instead of the bus IDs. Moreover, now the user can choose a plate number using the drop-down menu in a filter row cell to filter records, or a column cell to edit this cell. If these features are not required, assign false to the allowFiltering or allowEditing column option correspondingly.

Show Example:

In this example, the "Format" is declared as a lookup column. To filter grid records by this column, use the select box appearing in this column's filter row cell. Additionally, you can edit grid records. Note that when you edit values in the "Format" column, a select box similar to the filtering one does not let you enter any values other than those represented in the select box.




Specifies whether or not a user can nullify values of a lookup column.

Type: Boolean
Default Value: false

By default, when editing, a user cannot assign null to a cell of a lookup column. But if your data source accepts null values, set the lookup | allowClearing option to true for the column. In this case, a cell of a lookup column in the editing state is supplied with a button that nullifies this cell's value.

Show Example:

In this example, "Format" is declared as a lookup column. When a cell of this column is in the editing state, it is supplied with a button that nullifies its value. You can hide this button at runtime by toggling the check box under the grid.




Specifies the data source providing data for a lookup column.

Default Value: undefined

In order to have correspondence between the values from the main data source and those values that need to be displayed, specify a lookup data source. This data source can be one of the following.

  • An Array of objects
    The fields of each object will be used to provide data for the lookup select box.

  • A DataSource Configuration Object
    The DataSource is a stateful object that includes options for data sorting, grouping, filtering; it also keeps data transformation options and applies them each time data is loaded. The DataSource also provides events intended to handle changing data and the state. The DataSource underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. To learn more, refer to the Data Layer topic.

The lookup data source must contain fields that are used to define the valueExpr and displayExpr options of the lookup configuration object.

When using a CustomStore to specify a data source for a lookup column, implementing its load and byKey functions is mandatory.


Specifies the expression defining the data source field whose values must be displayed.

Type: String|function(data)
Function parameters:
data: Object
A data object.
Default Value: undefined

This option specifies the field of the data source whose values must be displayed in place of the values of the field defined by the valueExpr option. When you need to simply substitute values of one field for values of another, assign the names of these fields to the valueExpr and displayExpr fields of the lookup object correspondingly. In case you need to compound the value to be displayed from several data source fields, assign a callback function returning this value to the displayExpr option. Within this function, you can access the object of the lookup data source using the function's parameter.


Specifies the expression defining the data source field whose values must be replaced.

Type: String
Default Value: undefined

This option specifies the field of the data source whose values must be replaced by the values of the field defined by the displayExpr option.