JavaScript/jQuery SelectBox - Getting Started

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 UI component 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 following sections for details on each configuration step. You can also find the full code in the following GitHub repository: getting-started-with-selectbox.

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.1.16/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/20.1.16/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/20.1.16/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 UI component'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 properties 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 property and set the SelectBox's grouped property 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 UI component's data is grouped.

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

Customize the Drop-Down Menu

The SelectBox uses the Popup component as the drop-down menu. To customize the menu, specify Popup properties in the dropDownOptions object. For example, the following code sets the height of SelectBox's drop-down menu to 150 pixels:

jQuery
index.js
$(function() {
    $("#selectBox").dxSelectBox({
        // ...
        dropDownOptions: {
            height: 150
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-select-box ...
    [dropDownOptions]="dropDownOptions">
</dx-select-box>
// ...
export class AppComponent {
    // ...
    dropDownOptions = {
        height: 150
    }
}
Vue
App.vue
<template>
    <DxSelectBox ...
        :drop-down-options="dropDownOptions"
    />
</template>

<script>
// ...
export default {
    data() {
        return {
            // ...
            dropDownOptions: {
                height: 150
            }
        };
    }
}
</script>
React
App.js
// ...
const dropDownOptions = {
    height: 150
};

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

export default App;