Getting Started with Toolbar

NOTE
Before you start the tutorial, ensure DevExtreme is installed in your Angular, Vue, React, or jQuery application.

This tutorial shows how to add a Toolbar component to your application and configure its core features.

Each section in this tutorial describes a single configuration step. You can also find the full code in the following GitHub repository: getting-started-with-toolbar.

You can add items to the Toolbar in four areas: left area, central area, right area, and overflow menu. Templates help you customize items displayed in any of these sections. Refer to the following tutorial steps for details:

Create a Toolbar and its Items

To create a Toolbar, declare the component in the markup and add at least one item.

You can use the items array or specify a dataSource to populate a Toolbar with items. A Toolbar item can display plain text (text) or a UI component (widget). If the item is a UI component, declare its options.

The following list shows all UI components that you can use in the Toolbar:

In Angular, Vue, and React, import modules for all the components except the dxButton.

The following code creates a Toolbar and adds a dxTextBox and dxButton. The button responds to user clicks. The Toolbar displays these items in the center.

jQuery
index.js
index.html
$(function() {
    function showMessage(name) {
        DevExpress.ui.notify(
            {
                message: `${name} button has been clicked!`,
                width: 300
            },
            'info',
            500
        );
    };

    $("#toolbar").dxToolbar({
        items: [
            {
                widget: 'dxTextBox',
                options: {
                    placeholder: 'Search...',
                    showClearButton: true
                }
            },
            {
                widget: 'dxButton',
                options: {
                    icon: 'search',
                    onClick() {
                        showMessage('Search');
                    }
                }
            }
        ]
    });

});
<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/22.1.5/css/dx.light.css">
        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/22.1.5/js/dx.all.js"></script>
        <script type="text/javascript" src="index.js"></script>
        <link rel="stylesheet" type="text/css" href="index.css">
    </head>
    <body>
        <div id="toolbar"></div>
    </body>
</html>
Angular
app.component.html
app.component.ts
app.module.ts
<dx-toolbar>
    <dxi-item 
        widget="dxTextBox" 
        [options]="textBoxOptions"
    >
    </dxi-item>
    <dxi-item  
        widget="dxButton" 
        [options]="searchButtonOptions"
    >
    </dxi-item>
</dx-toolbar>
import { Component } from '@angular/core';
import notify from 'devextreme/ui/notify';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    textBoxOptions = {
        placeholder: 'Search...',
        showClearButton: true
    }

    searchButtonOptions = {
        icon: 'search',
        onClick() {
            showMessage('Search');
        }
    }
}

function showMessage(name: string) {
    notify(
        {
            message: `${name} button has been clicked!`,
            width: 300
        },
        'info',
        500
    );
};
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxToolbarModule, DxTextBoxModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxToolbarModule,
        DxTextBoxModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxToolbar>
        <dxItem 
            widget="dxTextBox" 
            :options="textBoxOptions"
        >
        </dxItem>
        <dxItem  
            widget="dxButton" 
            :options="searchButtonOptions"
        >
        </dxItem>
    </DxToolbar>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';
import DxToolbar, { DxItem } from 'devextreme-vue/toolbar';
import notify from "devextreme/ui/notify";
import 'devextreme/ui/text_box';

export default {
    components: {
        DxToolbar
        DxItem
    },
    data() {
        return {
            textBoxOptions: {
                placeholder: 'Search...',
                showClearButton: true
            },
            searchButtonOptions: {
                icon: 'search',
                onClick: () => {
                    this.showMessage('Search');
                }
            }
        }
    },
    methods: {    
        showMessage(name) {
            notify(
                {
                    message: `${name} button has been clicked!`,
                    width: 300
                },
                'info',
                500
            );
        }
    }
}
</script>
React
App.js
import React from 'react';
import Toolbar, { Item } from 'devextreme-react/toolbar';
import notify from 'devextreme/ui/notify';
import 'devextreme/ui/text_box';

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

const showMessage = (name) => {
    notify(
        {
            message: `${name} button has been clicked!`,
            width: 300
        },
        'info',
        500
    );
}

const textBoxOptions = {
    placeholder: 'Search...',
    showClearButton: true
}

const searchButtonOptions = {
    icon: 'search',
    onClick() {
        showMessage('Search');
    }
}

function App() {
    return (
        <Toolbar>
            <Item  
                widget="dxTextBox" 
                options={textBoxOptions}
            >
            </Item>
            <Item 
                widget="dxButton" 
                options={searchButtonOptions}
            >
            </Item>
        </Toolbar>
    );
}

export default App;

Specify Item Location

Specify the location property for each item. The following location values are available:

  • "center" (default)
    Places the item in the center of the toolbar.

  • "before"
    Places the item before the central element(s).

  • "after"
    Places the item after the central element(s).

The following code snippet adds a button before the central elements and a button after.

jQuery
index.js
$(function() {
    // ...

    $("#toolbar").dxToolbar({
        items: [
            // ...
            {
                location: 'before',
                widget: 'dxButton',
                options: {
                    icon: 'back',
                    onClick() {
                        showMessage('Back');
                    }
                }
            },
            {
                location: 'after',
                widget: 'dxButton',
                options: {
                    icon: 'info',
                    text: 'About',
                    onClick() {
                        showMessage('About');
                    }
                }
            }
        ]
    });

});
Angular
app.component.html
app.component.ts
<dx-toolbar>
    <!-- ... -->
    <dxi-item 
        location="before" 
        widget="dxButton" 
        [options]="backButtonOptions"
    >
    </dxi-item>
    <dxi-item 
        location="after" 
        widget="dxButton"
        [options]="aboutButtonOptions"
    >
    </dxi-item>
</dx-toolbar>
// ...

export class AppComponent {
    // ...
    backButtonOptions = {
        icon: 'back',
        onClick() {
            showMessage('Back');
        }
    }
    aboutButtonOptions = {
        icon: 'info',
        text: 'About',
        onClick() {
            showMessage('About');
        }
    }
}
Vue
App.vue
<template>
    <DxToolbar>
        <!-- ... -->
        <dxItem 
            location="before" 
            widget="dxButton" 
            :options="backButtonOptions"
        >
        </dxItem>
        <dxItem 
            location="after" 
            widget="dxButton"
            :options="aboutButtonOptions"
        >
        </dxItem>
    </DxToolbar>
</template>

<script>
// ...

export default {
    components: {
        // ...
    },
    data() {
        return {
            // ...
            backButtonOptions: {
                icon: 'back',
                onClick: () => {
                    this.showMessage('Back');
                }
            },
            aboutButtonOptions: {
                icon: 'info',
                text: 'About',
                onClick: () => {
                    this.showMessage('About');
                }
            }
        };
    },
    methods: {    
        // ...
    }
}
</script>
React
App.js
// ...
const backButtonOptions = {
    icon: 'back',
    onClick() {
        showMessage('Back');
    }
}

const aboutButtonOptions = {
    icon: 'info',
    text: 'About',
    onClick() {
        showMessage('About');
    }
}

function App() {
    return (
        <Toolbar>
            <!-- ... -->
            <Item 
                location="before" 
                widget="dxButton" 
                options={backButtonOptions}
            >
            </Item>
            <Item 
                location="after" 
                widget="dxButton"
                options={aboutButtonOptions}
            >
            </Item>
        </Toolbar>
    );
}

export default App;

Customize Items

To apply the same customization to all items, use an itemTemplate. To customize an individual item, specify the template property of the item.

Note that Angular and Vue use custom templates instead of the template property. In React, specify the render property.

The following code adds a custom item after the Back button.

jQuery
index.js
index.css
$(function() {
    // ...

    $("#toolbar").dxToolbar({
        items: [
            // ...
            {   
                location: 'before',
                template: '<div id="back">Go back</div>'
            },
        ]
    });

});
#back {
    margin-left: 5px;
}
Angular
app.component.html
app.component.css
<dx-toolbar>
    <!-- ... -->
    <dxi-item
        location="before"
    >
        <div *dxTemplate>
            <div id="back">Go back</div>
        </div>
    </dxi-item>
</dx-toolbar>
#back {
    margin-left: 5px;
}
Vue
App.vue
<template>
    <DxToolbar>
        <!-- ... -->
        <dxItem
            location="before"
        >
            <div id="back">Go back</div>
        </dxItem>
    </DxToolbar>
</template>

<script>
// ...
</script>

<style>
    #back {
        margin-left: 5px;
    }
</style>
React
App.js
index.css
// ...
const renderBack = () => {
    return <div id="back">Go back</div>;
}

function App() {
    return (
        <Toolbar>
            <!-- ... -->
            <Item
                location="before"
                render={renderBack}
            >
            </Item>
        </Toolbar>
    );
}

export default App;
#back {
    margin-left: 5px;
}

Create an Overflow Menu

The Toolbar can render its items in the overflow menu. Specify the locateInMenu property for an item. Use one of the following values:

  • "always"
    Always places the item in the overflow menu. You can specify the order of items in the overflow menu.

  • "never" (default)
    Places the item outside of the overflow menu.

  • "auto"
    Places the item outside of the overflow menu. If all items cannot fit within the width of the Toolbar, it renders this item in the overflow menu. The Toolbar component determines the order of items in the overflow menu automatically.

If you want to customize an item in the overflow menu, specify menuItemTemplate.

The following code specifies locateInMenu="auto" for the About button and creates an overflow menu with three items. It also specifies the Toolbar width.

jQuery
index.js
index.css
$(function() {
    // ...

    $("#toolbar").dxToolbar({
        width: 500,
        items: [
            // ...
            {
                location: 'after',
                widget: 'dxButton',
                locateInMenu: 'auto',
                options: {
                    icon: 'info',
                    text: 'About',
                    onClick() {
                        showMessage('About');
                    }
                }
            },
            // ...
            {
                location: 'after',
                locateInMenu: 'always',
                template: '<div id="greeting">Hi <b>User</b>!</div>'
            },
            {
                location: 'after',
                widget: 'dxButton',
                locateInMenu: 'always',
                options: {
                    icon: 'user',
                    text: 'Profile',
                    onClick() {
                        showMessage('Profile');
                    }
                }
            },
            {
                location: 'after',
                widget: 'dxButton',
                locateInMenu: 'always',
                options: {
                    icon: 'preferences',
                    text: 'Settings',
                    onClick() {
                        showMessage('Settings');
                    }
                }
            }
        ]
    });

});
// ...
#greeting {
    text-align: center;
    margin: 7px;
}
Angular
app.component.html
app.component.ts
app.component.css
<dx-toolbar
    [width]="500"
>
    <!-- ... -->
    <dxi-item 
        location="after" 
        widget="dxButton"
        locateInMenu="auto"
        [options]="aboutButtonOptions"
    >
    </dxi-item>
    <!-- ... -->
    <dxi-item 
        location="after"
        locateInMenu="always" 
    >
        <div *dxTemplate>
            <div id="greeting">Hi <b>User</b>!</div>
        </div>
    </dxi-item>
    <dxi-item 
        location="after" 
        widget="dxButton"
        locateInMenu="always"
        [options]="profileButtonOptions"
    >
    </dxi-item>
    <dxi-item 
        location="after" 
        widget="dxButton"
        locateInMenu="always"
        [options]="settingsButtonOptions"
    >
    </dxi-item>
</dx-toolbar>
// ...

export class AppComponent {
    // ...
    profileButtonOptions = {
        icon: 'user',
        text: 'Profile',
        onClick() {
            showMessage('Profile');
        }
    }

    settingsButtonOptions = {
        icon: 'preferences',
        text: 'Settings',
        onClick() {
            showMessage('Settings');
        }
    }
}
// ...
#greeting {
    text-align: center;
    margin: 7px;
}
Vue
App.vue
<template>
    <DxToolbar
        :width="500"
    >
        <!-- ... -->
        <dxItem 
            location="after" 
            widget="dxButton"
            locate-in-menu="auto"
            :options="aboutButtonOptions"
        >
        </dxItem>
        <!-- ... -->
        <dxItem 
            location="after"
            locate-in-menu="always" 
        >
            <div id="greeting">Hi <b>User</b>!</div>
        </dxItem>
        <dxItem 
            location="after" 
            widget="dxButton"
            locate-in-menu="always"
            :options="profileButtonOptions"
        >
        </dxItem>
        <dxItem 
            location="after" 
            widget="dxButton"
            locate-in-menu="always"
            :options="settingsButtonOptions"
        >
        </dxItem>
    </DxToolbar>
</template>

<script>
// ...

export default {
    components: {
        // ...
    },
    data() {
        return {
            // ...
            profileButtonOptions: {
                icon: 'user',
                text: 'Profile',
                onClick: () => {
                    this.showMessage('Profile');
                }
            },
            settingsButtonOptions: {
                icon: 'preferences',
                text: 'Settings',
                onClick: () => {
                    this.showMessage('Settings');
                }
            }
        };
    },
    methods: {    
        // ...
    }
}
</script>

<style>
    // ...

    #greeting {
        text-align: center;
        margin: 7px;
    }
</style>
React
App.js
index.css
// ...

const profileButtonOptions = {
    icon: 'user',
    text: 'Profile',
    onClick() {
        showMessage('Profile');
    }
}

    const settingsButtonOptions = {
    icon: 'preferences',
    text: 'Settings',
    onClick() {
        showMessage('Settings');
    }
}

const renderGreeting = () => {
    return <div id="greeting">Hi <b>User</b>!</div>;
}

function App() {
    return (
        <Toolbar
            width={500}
        >
            <!-- ... -->
            <Item 
                location="after" 
                widget="dxButton"
                locateInMenu="auto"
                options={aboutButtonOptions}
            >
            <!-- ... -->
            </Item>
            <Item 
                location="after"
                locateInMenu="always"
                render={renderGreeting}
            >
            </Item>
            <Item 
                location="after" 
                widget="dxButton"
                locateInMenu="always"
                options={profileButtonOptions}
            >
            </Item>
            <Item 
                location="after" 
                widget="dxButton"
                locateInMenu="always"
                options={settingsButtonOptions}
            >
            </Item>
        </Toolbar>
    );
}

export default App;
// ...
#greeting {
    text-align: center;
    margin: 7px;
}