DevExtreme jQuery/JS - Getting Started with ButtonGroup

NOTE
Before starting the tutorial, make sure that you have installed DevExtreme in your application as described in the Installation section (for JavaScript libraries), the Getting Started article (for ASP.NET MVC 5 Controls), or the Configure a Visual Studio Project article (for ASP.NET Core Controls).

The ButtonGroup is a set of toggle buttons that can be used as a mode switcher.

This tutorial describes how to configure basic ButtonGroup features. We create a ButtonGroup that logs the names of the selected buttons into the browser's console (open the console to see them):

Refer to the subtopics for details on every configuration step. You can also see the full code below:

jQuery
index.js
index.html
const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

$(function() {
    $("#myButtonGroup").dxButtonGroup({
        items: fontStyles,
        keyExpr: "style",
        selectionMode: "multiple",
        selectedItemKeys: [ "italic" ],
        onSelectionChanged: function (e) {
            const selectedItemKeys = e.component.option("selectedItemKeys");
            let message;
            if(selectedItemKeys.length > 0) {
                message = "The following styles are selected: " + selectedItemKeys.join(", ");
            } else {
                message = "There are no selected styles"
            }
            console.log(message);
        }
    });
});
<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/19.2.15/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/19.2.15/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/19.2.15/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="myButtonGroup"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.module.ts
<dx-button-group
    [items]="fontStyles"
    keyExpr="style"
    selectionMode="multiple"
    [(selectedItemKeys)]="selectedFontStyleNames"
    (onSelectionChanged)="logSelectionChanged($event)">
</dx-button-group>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    fontStyles: Array<{ icon: string, style: string }> = [{
        icon: "bold",
        style: "bold"
    }, {
        icon: "italic",
        style: "italic"
    }, {
        icon: "underline",
        style: "underline"
    }, {
        icon: "strike",
        style: "strike"
    }];

    selectedFontStyleNames: string[] = [ "italic" ];

    constructor() {
        this.logSelectionChanged = this.logSelectionChanged.bind(this);
    }

    logSelectionChanged() {
        let message;
        if(this.selectedFontStyleNames.length > 0) {
            message = "The following styles are selected: " + this.selectedFontStyleNames.join(", ");
        } else {
            message = "There are no selected styles";
        }
        console.log(message);
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxButtonGroupModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxButtonGroupModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template> 
    <DxButtonGroup
        :items="fontStyles"
        key-expr="style"
        selection-mode="multiple"
        :selected-item-keys.sync="selectedFontStyleNames"
        @selection-changed="logSelectionChanged"
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxButtonGroup } from 'devextreme-vue/button-group';

const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

export default {
    components: {
        DxButtonGroup
    },
    data() {
        return {
            fontStyles,
            selectedFontStyleNames: [ 'italic' ]
        }
    },
    methods: {
        logSelectionChanged() {
            let message;
            if(this.selectedFontStyleNames.length > 0) {
                message = "The following styles are selected: " + this.selectedFontStyleNames.join(", ");
            } else {
                message = "There are no selected styles";
            }
            console.log(message);
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { ButtonGroup } from 'devextreme-react/button-group';

const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

class App extends React.Component {
    selectedFontStyleNames = [ 'italic' ];

    render() {
        return (
            <ButtonGroup
                items={fontStyles}
                keyExpr="style"
                selectionMode="multiple"
                defaultSelectedItemKeys={this.selectedFontStyleNames}
                onSelectionChanged={this.logSelectionChanged}
            />
        );
    }

    logSelectionChanged(e) {
        const selectedItemKeys = e.component.option("selectedItemKeys");
        let message;
        if(selectedItemKeys.length > 0) {
            message = "The following styles are selected: " + selectedItemKeys.join(", ");
        } else {
            message = "There are no selected styles"
        }
        console.log(message);
    }
}

export default App;
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    .KeyExpr("style")
    .SelectionMode(ButtonGroupSelectionMode.Multiple)
    .Items(items => {
        items.Add().Icon("bold").Option("style", "bold");
        items.Add().Icon("italic").Option("style", "italic");
        items.Add().Icon("underline").Option("style", "underline");
        items.Add().Icon("strike").Option("style", "strike");
    })
    .SelectedItemKeys(new string[] { "italic" })
    .OnSelectionChanged("logSelectionChanged")
)

<script type="text/javascript">
    function logSelectionChanged (e) {
        const selectedItemKeys = e.component.option("selectedItemKeys");
        let message;
        if(selectedItemKeys.length > 0) {
            message = "The following styles are selected: " + selectedItemKeys.join(", ");
        } else {
            message = "There are no selected styles"
        }
        console.log(message);
    }
</script>

Create the ButtonGroup

You can use the following library- or framework-specific code to create the ButtonGroup:

jQuery
index.html
index.js
<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/19.2.15/css/dx.common.css">
        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/19.2.15/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/19.2.15/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body>
        <div id="myButtonGroup"></div>
    </body>
</html>
$(function() {
    $("#myButtonGroup").dxButtonGroup({
        // Configuration goes here
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-button-group
    <!-- Configuration goes here -->
>
</dx-button-group>
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 { DxButtonGroupModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxButtonGroupModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxButtonGroup
        <!-- Configuration goes here -->
    />
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { DxButtonGroup } from 'devextreme-vue/button-group';

export default {
    components: {
        DxButtonGroup
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { ButtonGroup } from 'devextreme-react/button-group';

class App extends React.Component {
    constructor(props) {
        super(props);
    }

    render() {
        return (
            <ButtonGroup
                // Configuration goes here
            />
        );
    }
}

export default App;
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    @* Configuration goes here *@
)

Add Buttons to the ButtonGroup

Buttons are configured by objects that can contain custom and predefined fields. For instance, the fontStyles array in the following code has four data objects with one predefined field (icon) and one custom field (style) each.

Assign the array to the items option and use the keyExpr to specify style as the key field. We log the field's values into the console at a later step.

jQuery
index.js
const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

$(function() {
    $("#myButtonGroup").dxButtonGroup({
        items: fontStyles,
        keyExpr: "style",
    });
});
Angular
app.component.html
app.component.ts
<dx-button-group
    [items]="fontStyles"
    keyExpr="style">
</dx-button-group>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    fontStyles: Array<{ icon: string, style: string }> = [{
        icon: "bold",
        style: "bold"
    }, {
        icon: "italic",
        style: "italic"
    }, {
        icon: "underline",
        style: "underline"
    }, {
        icon: "strike",
        style: "strike"
    }];
}
Vue
App.vue
<template> 
    <DxButtonGroup
        :items="fontStyles"
        key-expr="style"
    />
</template>

<script>
// ...
const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

export default {
    // ...
    data() {
        return {
            fontStyles
        }
    },
}
</script>
React
App.js
// ...
const fontStyles = [{
    icon: "bold",
    style: "bold"
}, {
    icon: "italic",
    style: "italic"
}, {
    icon: "underline",
    style: "underline"
}, {
    icon: "strike",
    style: "strike"
}];

class App extends React.Component {
    render() {
        return (
            <ButtonGroup
                items={fontStyles}
                keyExpr="style"
            />
        );
    }
}

export default App;
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    .KeyExpr("style")
    .Items(items => {
        items.Add().Icon("bold").Option("style", "bold");
        items.Add().Icon("italic").Option("style", "italic");
        items.Add().Icon("underline").Option("style", "underline");
        items.Add().Icon("strike").Option("style", "strike");
    })
)

If you run the code, you should see a ButtonGroup that contains four buttons but nothing happens when you click any of them.

Preselect a Button

Populate the selectedItemKeys array with the keys of the buttons that should be preselected. In this tutorial, we add the "italic" button to this array.

jQuery
index.js
$(function() {
    $("#myButtonGroup").dxButtonGroup({
        // ...
        selectedItemKeys: [ "italic" ],
    });
});
Angular
app.component.html
app.component.ts
<dx-button-group ...
    [(selectedItemKeys)]="selectedFontStyleNames">
</dx-button-group>
// ...
export class AppComponent {
    // ...
    selectedFontStyleNames: string[] = [ "italic" ];
}
Vue
App.vue
<template> 
    <DxButtonGroup ...
        :selected-item-keys.sync="selectedFontStyleNames"
    />
</template>

<script>
// ...
export default {
    // ...
    data() {
        return {
            // ...
            selectedFontStyleNames: [ 'italic' ]
        }
    }
}
</script>
React
App.js
// ...
class App extends React.Component {
    selectedFontStyleNames = [ 'italic' ];

    render() {
        return (
            <ButtonGroup ...
                defaultSelectedItemKeys={this.selectedFontStyleNames}
            />
        );
    }
}

export default App;
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    @* ... *@
    .SelectedItemKeys(new string[] { "italic" })
)

If you run the code now, you should see the "italic" button initially selected.

Handle the Selection Change Event

Assign a function to the onSelectionChanged option. In this tutorial, the function logs the added or removed style's name to the browser's console:

jQuery
index.js
$(function() {
    $("#myButtonGroup").dxButtonGroup({
        // ...
        onSelectionChanged: function (e) {
            if(e.addedItems[0]) {
                console.log("The following style is added: " + e.addedItems[0].style);
            }
            if(e.removedItems[0]) {
                console.log("The following style is removed: " + e.removedItems[0].style)
            }
        },
    });
});
Angular
app.component.html
app.component.ts
<dx-button-group ...
    (onSelectionChanged)="logSelectionChanged($event)">
</dx-button-group>
// ...
export class AppComponent {
    // ...
    logSelectionChanged(e) {
        if(e.addedItems[0]) {
            console.log("The following style is added: " + e.addedItems[0].style);
        }
        if(e.removedItems[0]) {
            console.log("The following style is removed: " + e.removedItems[0].style)
        }
    }
}
Vue
App.vue
<template>
    <DxButtonGroup ...
        @selection-changed="logSelectionChanged"
    />
</template>

<script>
// ...
export default {
    // ...
    methods: {
        logSelectionChanged(e) {
            if(e.addedItems[0]) {
                console.log("The following style is added: " + e.addedItems[0].style);
            }
            if(e.removedItems[0]) {
                console.log("The following style is removed: " + e.removedItems[0].style)
            }
        }
    }
}
</script>
React
App.js
// ...
class App extends React.Component {
    // ...
    render() {
        return (
            <ButtonGroup ...
                onSelectionChanged={this.logSelectionChanged}
            />
        );
    }

    logSelectionChanged(e) {
        if(e.addedItems[0]) {
            console.log("The following style is added: " + e.addedItems[0].style);
        }
        if(e.removedItems[0]) {
            console.log("The following style is removed: " + e.removedItems[0].style)
        }
    }
}
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    @* ... *@
    .OnSelectionChanged("logSelectionChanged")
)

<script type="text/javascript">
    function logSelectionChanged (e) {
        if(e.addedItems[0]) {
            console.log("The following style is added: " + e.addedItems[0].style);
        }
        if(e.removedItems[0]) {
            console.log("The following style is removed: " + e.removedItems[0].style)
        }
    }
</script>

Run the code, open the browser's console, and select or clear the button selection in the ButtonGroup. You should see messages like the following:

The following style is added: underline
The following style is removed: bold

Enable Multiple Selection

Set the selectionMode option to "multiple" to allow users to select multiple buttons. You can also change the onSelectionChanged handler from the previous step to log all the selected styles in the console:

jQuery
index.js
$(function() {
    $("#myButtonGroup").dxButtonGroup({
       // ...
       selectionMode: "multiple",
       onSelectionChanged: function (e) {
            const selectedItemKeys = e.component.option("selectedItemKeys");
            let message;
            if(selectedItemKeys.length > 0) {
                message = "The following styles are selected: " + selectedItemKeys.join(", ");
            } else {
                message = "There are no selected styles"
            }
            console.log(message);
        }
    });
});
Angular
app.component.html
app.component.ts
<dx-button-group ...
    selectionMode="multiple"
    [(selectedItemKeys)]="selectedFontStyleNames"
    (onSelectionChanged)="logSelectionChanged($event)">
</dx-button-group>
// ...
export class AppComponent {
    // ...
    selectedFontStyleNames: string[] = [ "italic" ];

    constructor() {
        this.logSelectionChanged = this.logSelectionChanged.bind(this);
    }

    logSelectionChanged() {
        let message;
        if(this.selectedFontStyleNames.length > 0) {
            message = "The following styles are selected: " + this.selectedFontStyleNames.join(", ");
        } else {
            message = "There are no selected styles";
        }
        console.log(message);
    }
}
Vue
App.vue
<template> 
    <DxButtonGroup ...
        selection-mode="multiple"
        :selected-item-keys.sync="selectedFontStyleNames"
        @selection-changed="logSelectionChanged"
    />
</template>

<script>
// ...
export default {
    // ...
    data() {
        return {
            // ...
            selectedFontStyleNames: [ 'italic' ]
        }
    },
    methods: {
        logSelectionChanged() {
            let message;
            if(this.selectedFontStyleNames.length > 0) {
                message = "The following styles are selected: " + this.selectedFontStyleNames.join(", ");
            } else {
                message = "There are no selected styles";
            }
            console.log(message);
        }
    }
}
</script>
React
App.js
// ...
class App extends React.Component {
    render() {
        return (
            <ButtonGroup ...
                selectionMode="multiple"
                onSelectionChanged={this.logSelectionChanged}
            />
        );
    }

    logSelectionChanged(e) {
        const selectedItemKeys = e.component.option("selectedItemKeys");
        let message;
        if(selectedItemKeys.length > 0) {
            message = "The following styles are selected: " + selectedItemKeys.join(", ");
        } else {
            message = "There are no selected styles"
        }
        console.log(message);
    }
}

export default App;
ASP.NET MVC Controls
Index.cshtml
@(Html.DevExtreme().ButtonGroup()
    @* ... *@
    .SelectionMode(ButtonGroupSelectionMode.Multiple)
    .OnSelectionChanged("logSelectionChanged")
)

<script type="text/javascript">
    function logSelectionChanged (e) {
        const selectedItemKeys = e.component.option("selectedItemKeys");
        let message;
        if(selectedItemKeys.length > 0) {
            message = "The following styles are selected: " + selectedItemKeys.join(", ");
        } else {
            message = "There are no selected styles"
        }
        console.log(message);
    }
</script>

Now you should be able to select multiple buttons and see messages like the following in the console:

The following styles are selected: bold, underline, strike

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