Angular 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.

Each section in this tutorial covers a single 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

Add DevExtreme to your jQuery application and use the following code to create a SelectBox:

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/21.1.11/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/21.1.11/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="selectBox"></div>
    </body>
</html>
Angular

Add DevExtreme to your Angular application and use the following code to create a SelectBox:

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

Add DevExtreme to your Vue application and use the following code to create a SelectBox:

App.vue
<template>
    <DxSelectBox/>
</template>

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

export default {
    components: {
        DxSelectBox
    }
}
</script>
React

Add DevExtreme to your React application and use the following code to create a SelectBox:

App.js
import React from 'react';

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

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

function App() {
    return (
        <SelectBox
            {/* Configuration goes here */}
        >
        </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 SelectBox to Data

The SelectBox can load data from different data source types. To use a local array, assign it to the dataSource property. If array elements are objects, set the fields that supply the SelectBox's value (valueExpr) and displayed value (displayExpr). For information on other data source types, refer to the following articles:

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';

function App() {
    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
// ...

function App() {
    return (
        <SelectBox ...
            searchEnabled={true}
        />
    );
}
export default App;

This demo shows additional search properties:

View Demo

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

Handle the Value Change Event

Implement the onValueChanged handler to perform an action when a user selects an item. In the code below, this function logs the IDs of the currently and previously selected items.

jQuery
index.js
$(function() {
    $("#selectBox").dxSelectBox({
        // ...
        onValueChanged: function(e) {
            console.log(e.value);
            console.log(e.previousValue);
        },
    });
});
Angular
app.component.html
app.component.ts
<dx-select-box ...
    (onValueChanged)="onValueChanged($event)">
</dx-select-box>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    // ...
    onValueChanged(e) {
        console.log(e.previousValue);
        console.log(e.value);
    }
}
Vue
App.vue
<template>
    <DxSelectBox ...
        @value-changed="onValueChanged"
    />
</template>

<script>
export default {
    // ...
    methods: {
        onValueChanged(e) {
            console.log(e.previousValue);
            console.log(e.value);
        }
    }
}
</script>
React
App.js
import React, { useCallback } from 'react';

function App() { 
    const onValueChanged = useCallback((e) => {
        console.log(e.previousValue);
        console.log(e.value);
    }, []);

    return (
        <SelectBox ...
            onValueChanged={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 the DataSource's group property and set the SelectBox's grouped property to true.

jQuery
index.js
$(function() {
    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"
})

function App() {
    // ...
    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 the following article: Grouping in the Data Source. 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.

Customize the Drop-Down Menu

The SelectBox uses the Popup component as a 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
};

function App() {
    return (
        <SelectBox ...
            dropDownOptions={dropDownOptions}
        />
    );
}

export default App;

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