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>

General Information

.NET Subscription

Common Tools

Quality Assurance and Productivity

Desktop

Controls

Tools

Frameworks and Libraries

Web

Controls and Extensions

Tools

Maintenance Mode

Mobile

Enterprise and Analytic Tools

End-User Documentation

General Information

.NET Subscription

Common Tools

Quality Assurance and Productivity

Desktop

Controls

Tools

Frameworks and Libraries

Web

Controls and Extensions

Tools

Maintenance Mode

Mobile

Enterprise and Analytic Tools

End-User Documentation

JavaScript/jQuery DropDownBox - Overview

jQuery

Angular

Vue

React

ASP.NET MVC Controls

jQuery

Angular

Vue

React

ASP.NET MVC Controls

See Also