lookup

Specifies options of a lookup column.

Type: Object
Default Value: undefined

A lookup column restricts the set of values that can be chosen when a user edits or filters the column. In a lookup column, each cell is a drop-down menu. You can use a lookup column when you need to substitute displayed values with required values. For example, consider that you have two arrays of objects: drivers and buses.

JavaScript
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' }
];

All drivers have the busID field, which refers to a bus. If drivers is the main dataSource, the Bus ID column displays bus IDs, which provides little information to a user. It will be more useful to display bus license plates instead of IDs. For this, the buses array must be set as a lookup dataSource for the Bus ID column. Then, the names of data fields must be assigned to the valueExpr and displayExpr options. Values from the valueExpr data field will be replaced with values from the displayExpr data field.

jQuery
JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: 'busID',
            lookup: {
                dataSource: buses,
                valueExpr: 'busID',
                displayExpr: 'plates'
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-data-grid [dataSource]="drivers">
    <dxi-column dataField="busID">
        <dxo-lookup
            [dataSource]="buses"
            valueExpr="busID"
            displayExpr="plates">
        </dxo-lookup>
    </dxi-column>
</dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    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 }
    ];
    buses = [
        { busID: 1, plates: '123456' },
        { busID: 2, plates: 'AB-1234' },
        { busID: 3, plates: 'CD-9876' }
    ];
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

With this code, the Bus ID column contains license plates instead of IDs. Moreover, the user can choose a plate number from the drop-down menu when editing cells or applying a filter to this column.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

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.


                                    

                                    

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.


                                    

                                    

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.


                                    

                                    

allowClearing

Specifies whether a user can nullify values of the lookup column.

Type: Boolean
Default Value: false

Set this option to true only if your data source accepts null values. If you do, all cells of the lookup column in the editing state will have a button that nullifies the cell's value.

Show Example:
AngularJS
Knockout
jQuery

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.


                                    

                                    

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.


                                    

                                    

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.


                                    

                                    

dataSource

Specifies the data source for the lookup column.

Function parameters:
options: Object

The settings of a row.

Object structure:
data: Object

The data of the row.

key: any

The key value of the row.

Return Value: Array|DataSourceOptions

An array of data objects or a DataSource configuration object.

Default Value: undefined

This option accepts one of the following.

  • Array of Objects
    A simple JavaScript array containing a collection of plain objects.

  • DataSource Configuration Object
    A configuration object of the DataSource. Learn more about the DataSource and the DevExtreme Data Layer concept from the Data Layer topic.

    NOTE
    When using a CustomStore for the lookup data source, you are required to implement the load and byKey functions.
  • Function
    A function that returns either an array of objects or a DataSource configuration object.

The lookup data source must contain fields assigned to the valueExpr and displayExpr options.

See Also

displayExpr

Specifies the data source field whose values must be displayed.

Function parameters:
data: Object

A row's data.

Default Value: undefined

This option accepts a string - the name of the data field that provides displayed values, or a function that returns the displayed value, combined from values of several data fields.

NOTE

Values in a lookup column are sorted by the valueExpr field. Implement the column's calculateSortValue function if you want to sort by the displayExpr field instead:

jQuery
JavaScript
columns: [{
    // ...
    lookup: {
        // ...
    },
    calculateSortValue: function (data) {
        var value = this.calculateCellValue(data);
        return this.lookup.calculateCellValue(value);
    }
}]
Angular
HTML
TypeScript
<dxi-column
    ...
    [calculateSortValue]="calculateSortValue">
    <dxo-lookup ... ></dxo-lookup>
</dxi-column>
export class AppComponent {
    calculateSortValue (data) {
        let column = this as any;
        let value = column.calculateCellValue(data);
        return column.lookup.calculateCellValue(value);
    }
}

valueExpr

Specifies the data source field whose values must be replaced.

Type: String
Default Value: undefined

Values from this field will be replaced with values from the displayExpr field.