React SelectBox - Getting Started
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
$(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
<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
<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
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
$(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
<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
<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
// ... 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
$(function() { // ... $("#selectBox").dxSelectBox({ // ... searchEnabled: true }); });
Angular
<dx-select-box ... [searchEnabled]="true"> </dx-select-box>
Vue
<template> <DxSelectBox ... :search-enabled="true" /> </template> <script> // ... </script>
React
// ... class App extends React.Component { render() { return ( <SelectBox ... searchEnabled={true} /> ); } } export default App;
There are additional search properties demonstrated in the following 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
$(function() { $("#selectBox").dxSelectBox({ // ... onValueChanged: function(e) { const item = data.filter(i => i.ID === e.value)[0]; console.log(item.ID + ": " + item.Name); } }); });
Angular
<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
<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
// ... 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
$(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
<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
<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
// ... 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
$(function() { $("#selectBox").dxSelectBox({ // ... dropDownOptions: { height: 150 } }); });
Angular
<dx-select-box ... [dropDownOptions]="dropDownOptions"> </dx-select-box>
// ... export class AppComponent { // ... dropDownOptions = { height: 150 } }
Vue
<template> <DxSelectBox ... :drop-down-options="dropDownOptions" /> </template> <script> // ... export default { data() { return { // ... dropDownOptions: { height: 150 } }; } } </script>
React
// ... const dropDownOptions = { height: 150 }; class App extends React.Component { render() { return ( <SelectBox ... dropDownOptions={dropDownOptions} /> ); } } export default App;
If you have technical questions, please create a support ticket in the DevExpress Support Center.