Vue DropDownButton - Getting Started
jQuery
Angular
Vue
React
The DropDownButton combines the functionality of a button and a drop-down menu. You can replace the menu with a custom drop-down control.
This tutorial describes how to configure a DropDownButton that logs user clicks in the browser console (you can open the console to see the messages):
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-dropdownbutton.
Create a DropDownButton
You can use the following code to create a DropDownButton:
jQuery
<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.2.15/css/dx.light.css"> <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/21.2.15/js/dx.all.js"></script> <script type="text/javascript" src="index.js"></script> </head> <body class="dx-viewport"> <div id="myDropDownButton"></div> </body> </html>
$(function() { $("#myDropDownButton").dxDropDownButton({ // Configuration goes here }); });
Angular
<dx-drop-down-button <!-- Configuration goes here --> > </dx-drop-down-button>
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 { DxDropDownButtonModule } from 'devextreme-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, DxDropDownButtonModule ], providers: [ ], bootstrap: [AppComponent] }) export class AppModule { }
Vue
<template> <DxDropDownButton <!-- Configuration goes here --> /> </template> <script> import 'devextreme/dist/css/dx.light.css'; import DxDropDownButton from 'devextreme-vue/drop-down-button'; export default { components: { DxDropDownButton } } </script>
React
import React from 'react'; import 'devextreme/dist/css/dx.light.css'; import DropDownButton from 'devextreme-react/drop-down-button'; class App extends React.Component { render() { return ( <DropDownButton // Configuration goes here /> ); } } export default App;
Configure the Button
Specify the button's text and/or icon:
jQuery
$(function() { $("#myDropDownButton").dxDropDownButton({ text: "Sandra Johnson", icon: "user" }); });
Angular
<dx-drop-down-button text="Sandra Johnson" icon="user"> </dx-drop-down-button>
Vue
<template> <DxDropDownButton text="Sandra Johnson" icon="user" /> </template> <script> // ... </script>
React
// ... class App extends React.Component { render() { return ( <DropDownButton text="Sandra Johnson" icon="user" /> ); } }
Run the code and you should see a button that displays the specified text and icon. Click this button to open a drop-down menu that shows "No data to display." In the next step, we populate the menu.
Populate the Drop-Down Menu
Assign an array to the items property to populate the drop-down menu. Objects in this array should contain data fields that specify text, icons, and other menu item data. The data fields that match those listed in the items section are automatically recognized (icon
in the code below). To specify the field that stores item text, use the displayExpr property.
In addition, specify the data field that contains keys used to distinguish between menu items. You can use the keyExpr property to do it.
jQuery
const actions = [ { id: 1, text: "My profile", icon: "user" }, { id: 2, text: "Messages", icon: "email" }, { id: 3, text: "Contacts", icon: "group" }, { id: 4, text: "Log out", icon: "runner" } ]; $(function() { $("#myDropDownButton").dxDropDownButton({ // ... items: actions, keyExpr: "id", displayExpr: "text" }); });
Angular
<dx-drop-down-button ... [items]="actions" keyExpr="id" displayExpr="text"> </dx-drop-down-button>
// ... export class AppComponent { actions: Array<{id: Number, text: String, icon: String}> = [ { id: 1, text: "My profile", icon: "user" }, { id: 2, text: "Messages", icon: "email" }, { id: 3, text: "Contacts", icon: "group" }, { id: 4, text: "Log out", icon: "runner" } ]; }
Vue
<template> <DxDropDownButton ... :items="actions" key-expr="id" display-expr="text" /> </template> <script> // ... const actions = [ { id: 1, text: "My profile", icon: "user" }, { id: 2, text: "Messages", icon: "email" }, { id: 3, text: "Contacts", icon: "group" }, { id: 4, text: "Log out", icon: "runner" } ]; export default { // ... data() { return { actions } } } </script>
React
// ... const actions = [ { id: 1, text: "My profile", icon: "user" }, { id: 2, text: "Messages", icon: "email" }, { id: 3, text: "Contacts", icon: "group" }, { id: 4, text: "Log out", icon: "runner" } ]; class App extends React.Component { render() { return ( <DropDownButton ... items={actions} keyExpr="id" displayExpr="text" /> ); } }
If you run the code and click the button, you should see a list of three actions, but nothing happens when you click any of them. We fix this in the next step.
Handle the Menu Item Click Event
Assign a function to the onItemClick property. In this tutorial, the function logs the selected action's name in the browser's console:
jQuery
$(function() { $("#myDropDownButton").dxDropDownButton({ // ... onItemClick: function(e) { console.log(e.itemData.text + " was clicked"); } }); });
Angular
<dx-drop-down-button ... (onItemClick)="logAction($event)"> </dx-drop-down-button>
// ... export class AppComponent { // ... logAction(e) { console.log(e.itemData.text + " was clicked"); } }
Vue
<template> <DxDropDownButton ... @item-click="logAction" /> </template> <script> // ... export default { // ... methods: { logAction(e) { console.log(e.itemData.text + " was clicked"); } } } </script>
React
// ... class App extends React.Component { logAction(e) { console.log(e.itemData.text + " was clicked"); } render() { return ( <DropDownButton ... onItemClick={this.logAction} /> ); } } export default App;
Run the code, open the browser's console, click the button, and select an action from the drop-down menu. You should see messages like the following:
My profile was clicked Messages was clicked Contacts was clicked
Split the Button
The button can execute a custom action instead of opening the drop-down menu. To enable this behavior, split the button into two sections. Set the splitButton property to true and assign a function to the onButtonClick property:
jQuery
$(function() { $("#myDropDownButton").dxDropDownButton({ // ... splitButton: true, onButtonClick: function() { console.log("Main button was clicked"); } }); });
Angular
<dx-drop-down-button ... [splitButton]="true" (onButtonClick)="logButtonClick()"> </dx-drop-down-button>
// ... export class AppComponent { // ... logButtonClick() { console.log("Main button was clicked"); } }
Vue
<template> <DxDropDownButton ... :split-button="true" @button-click="logButtonClick" /> </template> <script> // ... export default { // ... methods: { // ... logButtonClick() { console.log("Main button was clicked"); } } } </script>
React
// ... class App extends React.Component { // ... logButtonClick() { console.log("Main button was clicked"); } render() { return ( <DropDownButton ... splitButton={true} onButtonClick={this.logButtonClick} /> ); } } export default App;
If you run the code, you should see a button divided in two sections. A click on the main section logs "Main button was clicked" into the browser's console. A click on the secondary section opens the drop-down menu.
Enable the Stateful Mode
If the DropDownButton should remember the selected drop-down menu item, switch it to the stateful mode. Set the useSelectMode property to true and make the following replacements in your code:
Use onSelectionChanged instead of onItemClick.
You should track selection changes instead of handling item clicks.
Use the selectedItemKey to specify the initially selected item.
In stateful mode, the main button area displays the text and icon from the selected item. The selectedItemKey allows you to get or set the current selection. Items are identified using keys from the data field that you assigned to the keyExpr property (see the Populate the Drop-Down Menu step).
For more information on the stateful mode, refer to the useSelectMode description.
jQuery
$(function() { $("#myDropDownButton").dxDropDownButton({ // ... // text: "Sandra Johnson", // icon: "user" // onItemClick: function(e) { // console.log(e.itemData.text + " was clicked"); // }, useSelectMode: true, selectedItemKey: 1, onSelectionChanged: function(e) { console.log(e.item.text + " was selected; " + e.previousItem.text + " was deselected"); } }); });
Angular
<dx-drop-down-button ... <!-- text="Sandra Johnson" --> <!-- icon="user" --> <!-- (onItemClick)="logAction($event)" --> [useSelectMode]="true" [selectedItemKey]="1" (onSelectionChanged)="logSelectionChanged($event)"> </dx-drop-down-button>
// ... export class AppComponent { // ... // logAction(e) { // console.log(e.itemData.text + " was clicked"); // } logSelectionChanged(e) { console.log(e.item.text + " was selected; " + e.previousItem.text + " was deselected"); } }
Vue
<template> <DxDropDownButton <!-- text="Sandra Johnson" --> <!-- icon="user" --> <!-- @item-click="logAction" --> :use-select-mode="true" :selected-item-key="1" @selection-changed="logSelectionChanged" /> </template> <script> // ... export default { // ... methods: { // ... // logAction(e) { // console.log(e.itemData.text + " was clicked"); // } logSelectionChanged(e) { console.log(e.item.text + " was selected; " + e.previousItem.text + " was deselected"); } } } </script>
React
// ... class App extends React.Component { // ... // logAction(e) { // console.log(e.itemData.text + " was clicked"); // } logSelectionChanged(e) { console.log(e.item.text + " was selected; " + e.previousItem.text + " was deselected"); } render() { return ( <DropDownButton // text="Sandra Johnson" // icon="user" // onItemClick={this.logAction} useSelectMode={true} selectedItemKey={1} onSelectionChanged={this.logSelectionChanged} /> ); } } export default App;
Run the code, open the drop-down menu, and select an item. You should see that the button's text and icon are changed according to the item you selected. In addition, the browser's console should contain messages like the following:
My profile was selected; Log out was deselected Contacts was selected; My profile was deselected
You have configured basic DropDownButton features. For more information about this UI component, explore the following resources:
Customize the Drop-Down Menu
The DropDownButton 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 the DropDownButton's menu to 150 pixels:
jQuery
$(function() { $("#myDropDownButton").dxDropDownButton({ // ... dropDownOptions: { height: 150 } }); });
Angular
<dx-drop-down-button ... [dropDownOptions]="dropDownOptions"> </dx-drop-down-button>
// ... export class AppComponent { // ... dropDownOptions = { height: 150 } }
Vue
<template> <DxDropDownButton ... :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 ( <DropDownButton ... dropDownOptions={dropDownOptions} /> ); } } export default App;
If you have technical questions, please create a support ticket in the DevExpress Support Center.