Box
Map
Row
Vue

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() {
    $("#treeListContainer").dxTreeList({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: "busID",
            lookup: {
                dataSource: buses,
                valueExpr: "busID",
                displayExpr: "plates"
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list [dataSource]="drivers">
    <dxi-column dataField="busID">
        <dxo-lookup
            [dataSource]="buses"
            valueExpr="busID"
            displayExpr="plates">
        </dxo-lookup>
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})

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.

See Also

allowClearing

Specifies whether to display the Clear button in lookup column cells while they are being edited.

Type:

Boolean

Default Value: false

Set this option to true only if your data source accepts null values.

To specify this option based on a condition, set the showClearButton option instead. This is an option of the SelectBox widget which is used as an editor for lookup column cells. allowClearing is an alias for this option in the TreeList. The following code shows how to set showClearButton in the onEditorPreparing event handler:

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        onEditorPreparing: function (e) {
            if (/* a condition to set the option's value */) {
                e.editorOptions.showClearButton = true;
            }
        }
    });
});
Angular
app.component.ts
app.module.ts
app.component.html
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    onEditorPreparing(e) {
        if (/* a condition to set the option's value */) {
            e.editorOptions.showClearButton = true;
        }
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    bootstrap: [AppComponent]
})
export class AppModule { }
<dx-tree-list ...
    (onEditorPreparing)="onEditorPreparing($event)">
    <!-- ... -->
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList ...
        :on-editor-preparing="onEditorPreparing">
        <!-- ... -->
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import DxTreeList from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList
    },
    // ...
    methods: {
        onEditorPreparing(e) {
            if (/* a condition to set the option's value */) {
                e.editorOptions.showClearButton = true;
            }
        }
    }
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import TreeList from 'devextreme-react/tree-list';

class App extends React.Component {
    onEditorPreparing(e) {
        if (/* a condition to set the option's value */) {
            e.editorOptions.showClearButton = true;
        }
    }

    render() {
        return (
            <TreeList ...
                onEditorPreparing={this.onEditorPreparing}>
                {/* ... */}
            </TreeList>
        );
    }
}
export default App;

dataSource

Specifies the data source for the lookup column.

Function parameters:
options:

Object

Information on the current row.

Object structure:
Name Type Description
data

Object

The row's data.

key any

The row's key.

Return Value:

Array<any>

|

DataSource Configuration

|

Store

An array of objects or primitives, a store instance, or a DataSource configuration.

Default Value: undefined

This option accepts one of the following:

  • Array of objects or primitives
    A JavaScript array that contains plain objects or primitives.

  • DataSource configuration object
    A DataSource configuration object. For more information about the DataSource and DevExtreme Data Layer, refer to the Data Layer article.

    IMPORTANT
    DataSource instances are not supported.
  • Store instance
    An ArrayStore, LocalStore, ODataStore, or CustomStore instance.

  • Function
    A function that returns one of the above.

If the lookup data source contains objects, specify the valueExpr and displayExpr options in addition to the dataSource.

NOTE
Collections of primitives are not supported if you use the DevExtreme.AspNet.Data library API directly or via a server-side wrapper (as with the DevExtreme ASP.NET MVC Controls) to load the collections from a remote data source. Reconfigure the data source to return collections of objects.

View Demo

See Also

displayExpr

Specifies the data source field whose values must be displayed.

Type:

String

|

Function

Function parameters:
data:

Object

A row's data.

Return Value:

String

The displayed value.

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.

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.

NOTE
You cannot specify valueExpr as a function when the widget is bound to a remote data source. This is because valueExpr is used in a filter the widget sends to the server when querying data. Functions with custom logic cannot be serialized for this filter.