All docs
V20.2
21.2
21.1
20.2
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.
A newer version of this page is available. Switch to the current version.

Overview

The DropDownBox is a UI component that consists of a text field, which displays the current value, and a drop-down field, which can contain any UI element.

View Demo

The simplest UI component configuration requires specifying a dataSource, value and contentTemplate. The following code adds the DropDownBox to your page:

jQuery
JavaScript
$(function () {
    const fruits = ["Apples", "Oranges", "Lemons", "Pears", "Pineapples"];
    $("#dropDownBoxContainer").dxDropDownBox({
        value: fruits[0],
        dataSource: fruits,
        contentTemplate: function(e) {
            const $list = $("<div>").dxList({
                dataSource: e.component.option("dataSource"),
                selectionMode: "single",
                onSelectionChanged: function(arg) {
                    e.component.option("value", arg.addedItems[0]);
                    e.component.close();
                } 
            });
            return $list;
        }
    });
});
Angular
HTML
TypeScript
<dx-drop-down-box
    [(value)]="selectedFruit"
    [(opened)]="isDropDownBoxOpened"
    [dataSource]="fruits">
    <dx-list 
        [dataSource]="fruits"
        selectionMode="single"
        (onSelectionChanged)="changeDropDownBoxValue($event)">
    </dx-list>
</dx-drop-down-box>
import { DxDropDownBoxModule, DxListModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruits = ["Apples", "Oranges", "Lemons", "Pears", "Pineapples"];
    selectedFruit = this.fruits[0];
    isDropDownBoxOpened = false;
    changeDropDownBoxValue = function (args) {
        this.selectedFruit = args.addedItems[0];
        this.isDropDownBoxOpened = false;
    }
}
@NgModule({
    imports: [
        // ...
        DxDropDownBoxModule,
        DxListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <div>
        <DxDropDownBox
            v-model:value="selectedFruit"
            v-model:opened="isDropDownBoxOpened"
            :data-source="dataSource">
            <DxList
                :data-source="dataSource"
                selection-mode="single"
                @selection-changed="changeDropDownBoxValue($event)">
            </DxList>
        </DxDropDownBox>
    </div>
</template>

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

import DxDropDownBox from "devextreme-vue/drop-down-box";
import DxList from "devextreme-vue/list";

export default {
    components: {
        DxDropDownBox,
        DxList
    },
    data() {
        const fruits = ["Apples", "Oranges", "Lemons", "Pears", "Pineapples"];
        return {
            dataSource: fruits,
            isDropDownBoxOpened: false,
            selectedFruit: fruits[0]
        }
    },
    methods: {
        changeDropDownBoxValue(e) {
            this.selectedFruit = e.addedItems[0];
            this.isDropDownBoxOpened = false;
        }
    }
}
</script>
React
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DropDownBox } from 'devextreme-react/drop-down-box';
import { List } from 'devextreme-react/list';

const fruits = ['Apples', 'Oranges', 'Lemons', 'Pears', 'Pineapples'];

class App extends React.Component {
    constructor(props) {
        super(props);

        this.state = {
            selectedFruit: fruits[0]
        };

        this.dataSource = fruits;
        this.dropDownBoxRef = React.createRef();

        this.changeDropDownBoxValue = this.changeDropDownBoxValue.bind(this);
    }

    changeDropDownBoxValue(e) {
        this.setState({
            selectedFruit: e.addedItems[0]
        });
        this.dropDownBoxRef.current.instance.close();
    }

    render() {
        return (
            <DropDownBox
                ref={this.dropDownBoxRef}
                value={this.state.selectedFruit}
                dataSource={this.dataSource}>
                <List
                    dataSource={this.dataSource}
                    selectionMode="single"
                    onSelectionChanged={this.changeDropDownBoxValue}
                />
            </DropDownBox>
        );
    }
}

export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().DropDownBox()
    .ID("dropDownBox")
    .DataSource(new[] { "Apples", "Oranges", "Lemons", "Pears", "Pineapples" })
    .Value("Apples")
    .ContentTemplate(new TemplateName("list"))
)
@using (Html.DevExtreme().NamedTemplate("list")) {
    @(Html.DevExtreme().List()
        .DataSource(new JS("component.option('dataSource')"))
        .SelectionMode(ListSelectionMode.Single)
        .OnSelectionChanged("innerList_selectionChanged")
    )
}

<script>
    function innerList_selectionChanged (e) {
        const dropDownBox = $("#dropDownBox").dxDropDownBox("instance");
        dropDownBox.option("value", e.addedItems[0]);
        dropDownBox.close();
    }
</script>

If your data is an array of objects, specify:

  • valueExpr
    The data field whose value is written into the value property.
  • displayExpr
    The data field whose value is displayed in the input field of the UI component.
jQuery
JavaScript
$(function () {
    const customers = [
        { ID: 1, companyName: "Premier Buy", city: "Dallas", phone: "(233)2123-11" },
        { ID: 2, companyName: "ElectrixMax", city: "Naperville", phone: "(630)438-7800" },
        // ...
    ];
    const selectedValue = customers[0].ID;
    $("#dropDownBoxContainer").dxDropDownBox({
        value: selectedValue,
        valueExpr: "ID",
        displayExpr: "companyName",
        dataSource: new DevExpress.data.ArrayStore({
            data: customers,
            key: "ID"
        }),
        contentTemplate: function(e){
            const $dataGrid = $("<div>").dxDataGrid({
                dataSource: e.component.option("dataSource"),
                columns: ["companyName", "city", "phone"],
                height: 265,
                selection: { mode: "single" },
                selectedRowKeys: [selectedValue],
                onSelectionChanged: function(selectedItems){
                    const keys = selectedItems.selectedRowKeys,
                        hasSelection = keys.length;
                    e.component.option("value", hasSelection ? keys[0] : null); 
                    e.component.close();
                }
            });
            return $dataGrid;
        }
    });
});
Angular
HTML
TypeScript
<dx-drop-down-box
    [(value)]="selectedValue"
    [(opened)]="isDropDownBoxOpened"
    valueExpr="ID"
    displayExpr="companyName"
    [dataSource]="customerDataSource">
    <dx-data-grid 
        [dataSource]="customerDataSource"
        [selection]="{ mode: 'single' }"
        [columns]="['companyName', 'city', 'phone']"
        [height]="265"
        [(selectedRowKeys)]="selectedCustomers"
        (onSelectionChanged)="changeDropDownBoxValue($event)">
    </dx-data-grid>
</dx-drop-down-box>
import { DxDropDownBoxModule, DxDataGridModule } from "devextreme-angular";
import ArrayStore from "devextreme/data/array_store";
// ...
export class AppComponent  {
    customers = [
        { ID: 1, companyName: "Premier Buy", city: "Dallas", phone: "(233)2123-11" },
        { ID: 2, companyName: "ElectrixMax", city: "Naperville", phone: "(630)438-7800" },
        // ...
    ];
    customerDataSource = new ArrayStore({
        data: this.customers,
        key: "ID"
    });
    selectedCustomers = [this.customers[0].ID];
    selectedValue = this.selectedCustomers[0];
    isDropDownBoxOpened = false;
    changeDropDownBoxValue(args) {
        this.selectedValue = this.selectedCustomers[0];
        this.isDropDownBoxOpened = false;
    }
}
@NgModule({
    imports: [
        // ...
        DxDropDownBoxModule,
        DxDataGridModule
    ],
    // ...
})
Vue
App.vue
<template>
    <div>
        <DxDropDownBox
            v-model:value="selectedValue"
            v-model:opened="isDropDownBoxOpened"
            :data-source="customerDataSource"
            value-expr="ID"
            display-expr="companyName">
            <DxDataGrid
                :data-source="customerDataSource"
                :columns="['companyName', 'city', 'phone']"
                :height="265"
                v-model:selected-row-keys="selectedCustomers"
                @selection-changed="changeDropDownBoxValue">
                <DxSelection mode="single"/>
            </DxDataGrid>
        </DxDropDownBox>
    </div>
</template>

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

import DxDropDownBox from "devextreme-vue/drop-down-box";
import { DxDataGrid, DxSelection } from "devextreme-vue/data-grid";
import ArrayStore from "devextreme/data/array_store";

export default {
    components: {
        DxDropDownBox,
        DxDataGrid,
        DxSelection
    },
    data() {
        const customers = [
            { ID: 1, companyName: "Premier Buy", city: "Dallas", phone: "(233)2123-11" },
            { ID: 2, companyName: "ElectrixMax", city: "Naperville", phone: "(630)438-7800" },
            // ...
        ];
        return {
            customerDataSource: new ArrayStore({
                data: customers,
                key: "ID"
            }),
            isDropDownBoxOpened: false,
            selectedCustomers: [customers[0].ID],
            selectedValue: customers[0].ID
        }
    },
    methods: {
        changeDropDownBoxValue(e) {
            this.selectedValue = this.selectedCustomers[0];
            this.isDropDownBoxOpened = false;
        }
    }
}
</script>
React
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DropDownBox } from 'devextreme-react/drop-down-box';
import { DataGrid, Selection } from "devextreme-react/data-grid";
import ArrayStore from "devextreme/data/array_store";

const customers = [
    { ID: 1, companyName: "Premier Buy", city: "Dallas", phone: "(233)2123-11" },
    { ID: 2, companyName: "ElectrixMax", city: "Naperville", phone: "(630)438-7800" },
    // ...
];

class App extends React.Component {
    constructor(props) {
        super(props);

        this.state = {
            selectedCustomers: [customers[0].ID],
            selectedValue: customers[0].ID
        };

        this.customerDataSource = new ArrayStore({
            data: customers,
            key: "ID"
        });
        this.dropDownBoxRef = React.createRef();

        this.changeDropDownBoxValue = this.changeDropDownBoxValue.bind(this);
    }

    changeDropDownBoxValue(selectedItems) {
        const keys = selectedItems.selectedRowKeys;
        this.setState({
            selectedCustomers: keys,
            selectedValue: keys[0]
        });

        this.dropDownBoxRef.current.instance.close();
    }

    render() {
        return (
            <DropDownBox
                ref={this.dropDownBoxRef}
                value={this.state.selectedValue}
                dataSource={this.customerDataSource}
                valueExpr="ID"
                displayExpr="companyName">
                <DataGrid
                    dataSource={this.customerDataSource}
                    columns={['companyName', 'city', 'phone']}
                    height={265}
                    selectedRowKeys={this.state.selectedCustomers}
                    onSelectionChanged={this.changeDropDownBoxValue}>
                    <Selection mode="single"/>
                </DataGrid>
            </DropDownBox>
        );
    }
}

export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().DropDownBox()
    .ID("dropDownBox")
    .DataSource(ds => ds.Array()
        .Key("ID")
        .Data(new JS("customers"))
    )
    .Value(new JS("selectedValue"))
    .ValueExpr("ID")
    .DisplayExpr("companyName")
    .ContentTemplate(new TemplateName("dataGrid"))
)
@using (Html.DevExtreme().NamedTemplate("dataGrid")) {
    @(Html.DevExtreme().DataGrid()
        .DataSource(new JS("component.option('dataSource')"))
        .Columns(c => {
            c.Add().DataField("companyName");
            c.Add().DataField("city");
            c.Add().DataField("phone");
        })
        .Height(265)
        .Selection(s => s.Mode(SelectionMode.Single))
        .SelectedRowKeys(new JS("selectedValue"))
        .OnSelectionChanged("innerDataGrid_selectionChanged")
    )
}

<script>
    const customers = [
        { ID: 1, companyName: "Premier Buy", city: "Dallas", phone: "(233)2123-11" },
        { ID: 2, companyName: "ElectrixMax", city: "Naperville", phone: "(630)438-7800" }, 
        // ...
    ];
    const selectedValue = customers[0].ID;
    function innerDataGrid_selectionChanged(selectedItems) {
        const keys = selectedItems.selectedRowKeys,
            hasSelection = keys.length,
            dropDownBox = $("#dropDownBox").dxDropDownBox("instance");
        dropDownBox.option("value", hasSelection ? keys[0] : null);
        dropDownBox.close();
    }
</script>
See Also