JavaScript/jQuery SelectBox - Getting Started

Drop-down editors allow users to navigate through a list of items, select one or multiple items, and search through the list. To learn how to choose a DevExtreme drop-down editor and for more details about the component's features, refer to the following article: How to Choose a Drop-Down Editor.

jQuery
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
Angular
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
Vue
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
React
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your 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 describes a single configuration step. You can also find the full code in the GitHub repository.

View on GitHub

Create the SelectBox

jQuery

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

index.js
index.html
$(function() { 
    $("#selectBox").dxSelectBox({
        // Configuration goes here
    });
});
<html>
    <head>
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
        <link rel="stylesheet" type="text/css" href="https://cdn3.devexpress.com/jslib/minor_26_2/css/dx.fluent.blue.light.css" />
        <link rel="stylesheet" href="index.css" />

        <script src="https://cdn3.devexpress.com/jslib/minor_26_2/js/dx.all.js"></script>
        <script src="index.js"></script>
    </head>
    <body class="dx-viewport">
        <div id="selectBox"></div>
    </body>
</html>
ASP.NET Core Controls

Add DevExtreme to your ASP.NET Core application and use the following code snippet to create a SelectBox:

Index.cshtml
@(Html.DevExtreme().SelectBox()
    .ID("selectBox")
)
Angular

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

app.component.html
app.component.ts
<dx-select-box id="select-box">
    <!-- Configuration goes here -->
</dx-select-box>
import { Component } from '@angular/core';
import { DxSelectBoxModule } from 'devextreme-angular/ui/select-box';

@Component({ 
    imports: [DxSelectBoxModule],
    // ...
}) 
export class AppComponent { 

}
Vue

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

App.vue
<template> 
    <DxSelectBox id="select-box">
        <!-- Configuration goes here -->
    </DxSelectBox>
</template> 

<script setup lang="ts">
import 'devextreme/dist/css/dx.fluent.blue.light.css';
import { DxSelectBox } from 'devextreme-vue/select-box';

</script>
React

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

App.tsx
import 'devextreme/dist/css/dx.fluent.blue.light.css';
import './App.css';

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

export default function App() {
    return (
        <SelectBox id="select-box">
            {/* Configuration goes here */}
        </SelectBox>
    );
}

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"
    });
});
ASP.NET Core Controls
Index.cshtml
SelectBoxDataController.cs
SelectBoxItem.cs
SelectBoxData.cs
@(Html.DevExtreme().SelectBox()
    .DataSource(d => d
        .Mvc().Controller("SelectBoxData")
        .LoadAction("Get")
        .Key("ID")
    )
    .ValueExpr("ID")
    .DisplayExpr("Name")
)
using ASP_NET_Core.Models;
using DevExtreme.AspNet.Data;
using DevExtreme.AspNet.Mvc;
using Microsoft.AspNetCore.Mvc;

namespace ASP_NET_Core.Controllers;

public class SelectBoxDataController : Controller {

    [HttpGet]
    public object Get(DataSourceLoadOptions loadOptions) {
        return DataSourceLoader.Load(SelectBoxData.SelectBoxItems, loadOptions);
    }

}
namespace ASP_NET_Core.Models;
public class SelectBoxItem {
    public int ID { get; set; }
    public string Name { get; set; }
    public string Category { get; set; }
}
namespace ASP_NET_Core.Models;
static class SelectBoxData {
    public static List<SelectBoxItem> SelectBoxItems = [
        new SelectBoxItem {
            ID = 1,
            Name = "Banana",
            Category = "Fruits",
        },
        new SelectBoxItem {
            ID = 2,
            Name = "Cucumber",
            Category = "Vegetables",
        },
        new SelectBoxItem {
            ID = 3,
            Name = "Apple",
            Category = "Fruits",
        },
        new SelectBoxItem {
            ID = 4,
            Name = "Tomato",
            Category = "Vegetables",
        },
        new SelectBoxItem {
            ID = 5,
            Name = "Apricot",
            Category = "Fruits",
        },
    ];
}
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 { DxSelectBoxModule } from 'devextreme-angular/ui/select-box';
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 setup lang="ts">
import { DxSelectBox } from 'devextreme-vue/select-box';
import { data } from './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.tsx
data.js
import { SelectBox } from 'devextreme-react/select-box';
import { data } from './data';

export default function App() {
    return (
        <SelectBox
            dataSource={data}
            valueExpr="ID"
            displayExpr="Name"
        />
    ); 
}
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

Read Tutorial: Configure Search Parameters

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

jQuery
index.js
$("#selectBox").dxSelectBox({
    searchEnabled: true,
});
ASP.NET Core Controls
Index.cshtml
@(Html.DevExtreme().SelectBox()
    .SearchEnabled(true)
)
Angular
app.component.html
<dx-select-box
    [searchEnabled]="true"
></dx-select-box>
Vue
App.vue
<template>
    <DxSelectBox
        :search-enabled="true"
    />
</template>
React
App.tsx
import { SelectBox } from 'devextreme-react/select-box';

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

For more information about DevExtreme SelectBox search capabilities, review the following demo:

View Demo

Handle the Value Change Event

Use onValueChanged to specify a function that the component executes when users change the SelectBox value. The following example calls the notify utility method within this function:

jQuery
index.js
$("#selectBox").dxSelectBox({
    onValueChanged(e) {
        DevExpress.ui.notify(
            `Previous Value: ${e.previousValue}, Current Value: ${e.value}`,
            'info',
            2000,
        );
    },
    // ...
});
ASP.NET Core Controls
Index.cshtml
@(Html.DevExtreme().SelectBox()
    .OnValueChanged("handleValueChanged")
)

<script>
    function handleValueChanged(e) {
        DevExpress.ui.notify(
            `Previous Value: ${e.previousValue}, Current Value: ${e.value}`,
            'info',
            2000,
        );
    }
</script>
Angular
app.component.html
app.component.ts
<dx-select-box
    (onValueChanged)="onValueChanged($event)"
></dx-select-box>
import { DxSelectBoxModule, type DxSelectBoxTypes } from 'devextreme-angular/ui/select-box';
import notify from 'devextreme/ui/notify';

// ...
export class AppComponent {
    onValueChanged(e: DxSelectBoxTypes.ValueChangedEvent): void {
        notify(
            `Previous Value: ${e.previousValue}, Current Value: ${e.value}`,
            'info',
            2000,
        );
    }
}
Vue
App.vue
<template>
    <DxSelectBox
        @value-changed="onValueChanged"
    />
</template>

<script setup lang="ts">
import { DxSelectBox, type DxSelectBoxTypes } from 'devextreme-vue/select-box';
import notify from 'devextreme/ui/notify';

const onValueChanged = (e: DxSelectBoxTypes.ValueChangedEvent): void => {
    notify(
        `Previous Value: ${e.previousValue}, Current Value: ${e.value}`,
        'info',
        2000,
    );
};
</script>
React
App.tsx
import React, { useCallback } from 'react';
import { SelectBox, type SelectBoxTypes } from 'devextreme-react/select-box';
import notify from 'devextreme/ui/notify';

export default function App() { 
    const onValueChanged = useCallback((e: SelectBoxTypes.ValueChangedEvent) => {
        notify(
            `Previous Value: ${e.previousValue}, Current Value: ${e.value}`,
            'info',
            2000,
        );
    }, []);

    return (
        <SelectBox
            onValueChanged={onValueChanged}
        />
    );
}

Add a Label

Set the label property to specify label text. To enable floating labels, set labelMode to "floating". In floating mode, the label acts as a placeholder and moves above the input field when the editor receives focus.

jQuery
index.js
$("#selectBox").dxSelectBox({
    label: "Product",
    labelMode: "floating",
});
ASP.NET Core Controls
Index.cshtml
@(Html.DevExtreme().SelectBox()
    .Label("Product")
    .LabelMode(EditorLabelMode.Floating)
)
Angular
app.component.html
<dx-select-box
    label="Product"
    labelMode="floating">
</dx-select-box>
Vue
App.vue
<template>
    <DxSelectBox
        label="Product"
        label-mode="floating"
    />
</template>

<script setup lang="ts">
import { DxSelectBox } from 'devextreme-vue/select-box';

</script>
React
App.tsx
import { SelectBox } from 'devextreme-react/select-box';

export default function App() {
    return (
        <SelectBox
            label="Product"
            labelMode="floating"
        />
    );
}

View Demo

Group Data

Read Tutorial: Grouping in the Data Source

SelectBox can display grouped data. To implement this capability using a flat data source, follow these steps:

  1. Bind the component to a DataSource instance
  2. Specify the group field in the component DataSource
  3. Enable the grouped property
jQuery
index.js
const dataSource = new DevExpress.data.DataSource({
    store: {
        data,
        type: 'array',
        key: 'ID',
    },
    group: 'Category',
});

$("#selectBox").dxSelectBox({
    dataSource,
    grouped: true,
});
ASP.NET Core Controls
Index.cshtml
@(Html.DevExtreme().SelectBox()
    .DataSource(d => d
        .Mvc().Controller("SelectBoxData")
        .LoadAction("Get")
        .Key("ID")
    )
    .DataSourceOptions(o => o.Group("Category"))
    .Grouped(true)
)
Angular
app.component.html
app.component.ts
<dx-select-box
    [dataSource]="dataSource"
    [grouped]="true"
></dx-select-box>
import { DxSelectBoxModule } from 'devextreme-angular/ui/select-box';
import { DataSource } from 'devextreme-angular/common/data';

// ...
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
        :data-source="dataSource"
        :grouped="true"
    />
</template>

<script setup lang="ts">
import { DxSelectBox } from 'devextreme-vue/select-box';
import { DataSource } from 'devextreme-vue/common/data';

const dataSource = new DataSource({
    store: {
        data,
        type: 'array',
        key: 'ID',
    },
    group: 'Category',
});
</script>
React
App.tsx
import { SelectBox } from 'devextreme-react/select-box';
import { DataSource } from 'devextreme-react/common/data';

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

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

SelectBox can also display grouped data from a nested data source with one nesting level. Each object in the data source contains a key field and an items array. For more information, refer to the following guide: SelectBox - Grouping in the Data Source.

Customize the Drop-Down Menu

SelectBox uses the Popup component as a drop-down menu. To customize the menu, specify Popup properties in the dropDownOptions object:

jQuery
index.js
$("#selectBox").dxSelectBox({
    dropDownOptions: {
        height: 150,
    },
});
ASP.NET Core Controls
Index.cshtml
@(Html.DevExtreme().SelectBox()
    .DropDownOptions(o => o.Height(150))
)
Angular
app.component.html
<dx-select-box>
    <dxo-select-box-drop-down-options
        [height]="150"
    ></dxo-select-box-drop-down-options>
</dx-select-box>
Vue
App.vue
<template>
    <DxSelectBox>
        <DxDropDownOptions :height="150" />
    </DxSelectBox>
</template>

<script setup lang="ts">
import { DxSelectBox, DxDropDownOptions } from 'devextreme-vue/select-box';

</script>
React
App.tsx
import { SelectBox, DropDownOptions } from 'devextreme-react/select-box';

export default function App() {
    return (
        <SelectBox>
            <DropDownOptions height={150} />
        </SelectBox>
    );
}

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