Getting Started with SelectBox

NOTE
Before you start the tutorial, ensure DevExtreme is installed in your Angular, Vue, React, or jQuery application.

SelectBox is an editor that allows users to select a value from a drop-down list or add a new value.

In this tutorial, we will create the SelectBox and configure its basic features. The created widget has a populated drop-down list, allows users to search through it, and logs the previous and current selected items to the console.

Refer to the subtopics for details on every configuration step. You can also see the full code below or download it from this GitHub repository.

jQuery
index.js
index.html
$(function() {
    const data = [{
        ID: 1,
        Name: 'Banana',
        Category: 'Fruits',
    }, {
        ID: 2,
        Name: 'Cucumber',
        Category: 'Vegetables',
    }, {
        ID: 3,
        Name: 'Apple',
        Category: 'Fruits',
    }, {
        ID: 4,
        Name: 'Tomato',
        Category: 'Vegetables',
    }, {
        ID: 5,
        Name: 'Apricot',
        Category: 'Fruits',
    }]

    const dataSource = new DevExpress.data.DataSource({
        store: data,
        type: 'array',
        key: "ID",
        group: "Category"
    });

    $("#selectBox").dxSelectBox({
        dataSource: dataSource,
        valueExpr: "ID",
        displayExpr: "Name",
        searchEnabled: true,
        onValueChanged: function(e) {
            const item = data.filter(i => i.ID === e.value)[0];
            console.log(item.ID + ": " + item.Name);
        },
        grouped: true
    });
});
<html>
    <head>
        <!-- ... -->
        <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.2.3/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.2.3/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/20.2.3/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="selectBox"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.service.ts
app.module.ts
<dx-select-box
    [dataSource]="dataSource"
    valueExpr="ID"
    displayExpr="Name"
    [searchEnabled]="true"
    (onValueChanged)="onValueChanged($event)"
    [grouped]="true">
</dx-select-box>
import { Component } from '@angular/core';
import DataSource from 'devextreme/data/data_source';
import { AppService, Item } from './app.service';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    data: Item[];
    dataSource: DataSource;

    constructor(service: AppService) {
        this.data = service.getItems();
        this.dataSource = new DataSource({
            store: {
                data: this.data,
                type: 'array',
                key: 'ID'
            },
            group: "Category"
        });
    }

    onValueChanged(e) {
        const item = this.data.filter(i => i.ID === e.value)[0];
        console.log(item.ID + ": " + item.Name);
    }
}
import { Injectable } from '@angular/core';

export class Item {
    ID: number;
    Name: string;
    Category: string;
}

const items: Item[] = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}]

@Injectable()
export class AppService {
    getItems(): Item[] {
        return items;
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { DxSelectBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxSelectBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
data.js
<template>
    <DxSelectBox
        :data-source="dataSource"
        value-expr="ID"
        display-expr="Name"
        :search-enabled="true"
        @value-changed="onValueChange"
        :grouped="true"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';
import { DxSelectBox } from 'devextreme-vue/select-box';
import DataSource from 'devextreme/data/data_source';
import { data } from './data';

export default {
    components: {
        DxSelectBox
    },
    data() {
        return {
            dataSource: new DataSource({
                store: {
                    data: data,
                    type: 'array',
                    key: 'ID',
                },
                group: "Category"
            })
        }
    },
    methods: {
        onValueChange(e) {
            const item = data.filter(i => i.ID === e.value)[0];
            console.log(item.ID + ": " + item.Name);
        }
    },
}
</script>
export const data = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}];
React
App.js
data.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';
import { SelectBox } from 'devextreme-react/select-box';
import DataSource from 'devextreme/data/data_source';
import { data } from './data';

const dataSource = new DataSource({
    store: {
        data: data,
        type: 'array',
        key: 'ID'
    },
    group: "Category"
});

class App extends React.Component {
    onValueChanged(e) {
        const item = data.filter(i => i.ID === e.value)[0];
        console.log(item.ID + ": " + item.Name);
    }

    render() {
        return (
            <SelectBox
                dataSource={dataSource}
                valueExpr="ID"
                displayExpr="Name"
                searchEnabled={true}
                onValueChanged={this.onValueChanged}
                grouped={true}
            />
        );        
    }

}

export default App;
export const data = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}];

Create the SelectBox

Use the code below to create an empty SelectBox:

jQuery
index.js
index.html
$(function() {
    $("#selectBox").dxSelectBox({ });
});
<html>
    <head>
        <!-- ... -->
        <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.2.3/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.2.3/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/20.2.3/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="selectBox"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.module.ts
<dx-select-box></dx-select-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {

}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxSelectBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxSelectBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxSelectBox/>
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';
import { DxSelectBox } from 'devextreme-vue/select-box';

export default {
    components: {
        DxSelectBox
    }
}
</script>
React
App.js
import React from 'react';

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

import { SelectBox } from 'devextreme-react/select-box';

class App extends React.Component {
    render() {
        return (
            <SelectBox/>
        );
    }
}
export default App;

Run the code and ensure the SelectBox is displayed and its drop-down list says "No data to display." In the next step, we will add a data source.

Bind the SeleсtBox to Data

To bind the SelectBox to data, set the dataSource and the fields that provide the widget's value (valueExpr) and displayed value (displayExpr). In this tutorial, the SelectBox is bound to a local array.

jQuery
index.js
$(function() {
    const data = [{
        ID: 1,
        Name: 'Banana',
        Category: 'Fruits'
    }, {
        ID: 2,
        Name: 'Cucumber',
        Category: 'Vegetables'
    }, {
        ID: 3,
        Name: 'Apple',
        Category: 'Fruits'
    }, {
        ID: 4,
        Name: 'Tomato',
        Category: 'Vegetables'
    }, {
        ID: 5,
        Name: 'Apricot',
        Category: 'Fruits'
    }]

    $("#selectBox").dxSelectBox({
        dataSource: data,
        valueExpr: "ID",
        displayExpr: "Name"
    });
});
Angular
app.component.html
app.component.ts
app.service.ts
<dx-select-box
    [dataSource]="data"
    valueExpr="ID"
    displayExpr="Name">
</dx-select-box>
import { Component } from '@angular/core';
import { AppService, Item } from './app.service';

// ...
export class AppComponent {
    data: Item[];

    constructor(service: AppService) {
        this.data = service.getItems();
    }
}
import { Injectable } from '@angular/core';

export class Item {
    ID: number;
    Name: string;
    Category: string;
}

const items: Item[] = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}]

@Injectable()
export class AppService {
    getItems(): Item[] {
        return items;
    }
}
Vue
App.vue
data.js
<template>
    <DxSelectBox
        :data-source="data"
        value-expr="ID"
        display-expr="Name"
    />
</template>

<script>
// ...
import { data } from './data';

export default {
    components: {
        DxSelectBox
    },
    data() {
        return {
            data
        }
    }
}
</script>
export const data = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}];
React
App.js
data.js
// ...
import { data } from './data';

class App extends React.Component {
    render() {
        return (
            <SelectBox
                dataSource={data}
                valueExpr="ID"
                displayExpr="Name"
            />
        );        
    }

}

export default App;
export const data = [{
    ID: 1,
    Name: 'Banana',
    Category: 'Fruits',
}, {
    ID: 2,
    Name: 'Cucumber',
    Category: 'Vegetables',
}, {
    ID: 3,
    Name: 'Apple',
    Category: 'Fruits',
}, {
    ID: 4,
    Name: 'Tomato',
    Category: 'Vegetables',
}, {
    ID: 5,
    Name: 'Apricot',
    Category: 'Fruits',
}];

If you run this code and open the SelectBox, you will see the the populated drop-down list. Next, we will enable search.

Enable Search

To allow users to search through SelectBox values, set searchEnabled to true:

jQuery
index.js
$(function() {
        // ...

        $("#selectBox").dxSelectBox({
            // ...
            searchEnabled: true
        });
});
Angular
app.component.html
<dx-select-box ...
    [searchEnabled]="true">
</dx-select-box>
Vue
App.vue
<template>
    <DxSelectBox ...
        :search-enabled="true"
    />
</template>

<script>
    // ...
</script>
React
App.js
// ...

class App extends React.Component {
    render() {
        return (
            <SelectBox ...
                searchEnabled={true}
            />
        );
    }
}
export default App;

There are additional search options demonstrated in the following demo:

View Demo

In the next step, we will process the SelectBox's value change event.

Handle the Value Change Event

Implement the onValueChanged function to perform an action when a user selects an item. In the code below, this function logs the selected item's ID and Name.

jQuery
index.js
$(function() {
    $("#selectBox").dxSelectBox({
        // ...
        onValueChanged: function(e) {
            const item = data.filter(i => i.ID === e.value)[0];
            console.log(item.ID + ": " + item.Name);
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-select-box ...
    (onValueChanged)="handleValueChange($event)">
</dx-select-box>
// ...
export class AppComponent {
    // ...

    onValueChanged(e) {
        const item = this.data.filter(i => i.ID === e.value)[0];
        console.log(item.ID + ": " + item.Name);
    }
}
Vue
App.vue
<template>
    <DxSelectBox ...
        @value-changed="onValueChanged"            
    />
</template>

<script>
// ...

export default {
    // ...
    methods: {
        onValueChanged(e) {
            const item = data.filter(i => i.ID === e.value)[0];
            console.log(item.ID + ": " + item.Name);
        }
    },

}
</script>
React
App.js
// ...

class App extends React.Component {
    onValueChanged(e) {
        const item = data.filter(i => i.ID === e.value)[0];
        console.log(item.ID + ": " + item.Name);
    }

    render() {
        return (
            <SelectBox ...
                onValueChanged={this.onValueChanged}                   
            />
        );
    }
}
export default App;

Next, we will group the drop-down items.

Group Data

The SelectBox can display data grouped by category. To implement this, we will use the data from the previous steps with the DataSource component. Its API allows you to sort, filter, select, and group data. At its core, the DataSource has a store - an object that keeps data and provides an API to access and modify it. To configure the store, use the DataSource's store object. Specify its type as "array", pass the initial data array to the data field, and set the key field.

To group data, specify the data field to group by in the DataSource's group option and set the SelectBox's grouped option to true.

jQuery
index.js
$(function() {
    const data = [{
        ID: 1,
        Name: 'Banana',
        Category: 'Fruits',
    }, {
        ID: 2,
        Name: 'Cucumber',
        Category: 'Vegetables',
    }, {
        ID: 3,
        Name: 'Apple',
        Category: 'Fruits',
    }, {
        ID: 4,
        Name: 'Tomato',
        Category: 'Vegetables',
    }, {
        ID: 5,
        Name: 'Apricot',
        Category: 'Fruits',
    }]

    const dataSource = new DevExpress.data.DataSource({
        store: data,
        type: 'array',
        key: "ID",
        group: "Category"
    });

    $("#selectBox").dxSelectBox({
        // ...
         grouped: true
    });
});
Angular
app.component.html
app.component.ts
<dx-select-box ...
    [grouped]="true">
</dx-select-box>
// ...
import DataSource from 'devextreme/data/data_source';

// ...
export class AppComponent {
    data: Item[];
    dataSource: DataSource;

    constructor(service: AppService) {
        this.data = service.getItems();
        this.dataSource = new DataSource({
            store: {
                data: this.data,
                type: 'array',
                key: 'ID'
            },
            group: "Category"
        });
    }
    // ...
}
Vue
App.vue
<template>
    <DxSelectBox ...
        :grouped="true"
    />
</template>

<script>
// ...
import DataSource from 'devextreme/data/data_source';

export default {
    components: {
        DxSelectBox
    },
    data() {
        return {
            dataSource: new DataSource({
                store: {
                    data: data,
                    type: 'array',
                    key: 'ID',
                },
                group: "Category"
            })
        }
    },
    // ...
}
</script>
React
App.js
// ...
import DataSource from 'devextreme/data/data_source';

const dataSource = new DataSource({
    store: {
        data: data,
        type: 'array',
        key: 'ID'
    },
    group: "Category"
})

class App extends React.Component {
    // ...

    render() {
        return (
            <SelectBox ...
                grouped={true}
            />
        );        
    }

}

export default App;

If your data is already grouped, ensure each group has the key and items fields as shown in this article. If the fields are named differently, implement the DataSource's map function to create key + items field mappings.

Run the code and ensure the widget's data is grouped.

You have configured basic SelectBox features. To take a more detailed look at this widget, explore the following resources: