As you may already know, our next major update is set to ship in a few weeks. If you have not yet done so, please take a moment to review our
What’s New webpage for information on our upcoming release.
In this blog post, I’ll describe our new DataGrid and TreeList Toolbar Customization API and show you how to leverage its capabilities in your next DevExtreme-powered app.
New toolbar Property
In previous versions, you could customize our toolbar using the
onToolbarPreparing event handler. Though this approach addressed basic use cases, it did not allow you to modify the toolbar dynamically or configure the toolbar declaratively (important for Angular, React, and Vue users). To address this limitation, v21.2 ships with a new
toolbar property:
toolbar: {
visible: Boolean, // `true` - the toolbar is visible;
// `false` - the toolbar is hidden;
// `undefined` - the toolbar is visible if it contains items
disabled: Boolean, // Specifies whether the toolbar responds to user interaction
items: Object[] // Configures toolbar items
}
Common Use Cases
In the following sections, we’ll describe a few usage scenarios and discuss the use of our new toolbar property. Please note that while each code listing targets only one of our supported frameworks, all our new features are available for Angular, Vue, React, jQuery, ASP.NET MVC, and ASP.NET Core.
Add a Custom Toolbar Item
To configure toolbar items, you need to specify the
items array. This array can contain predefined items (Export button, Search Panel, etc.) and custom items. The following code adds a custom 'Refresh’ button to the toolbar. Note: You should also declare predefined items (such as the Column Chooser button) in your code if you wish to make them available to end-users.
Angular
<!-- app.component.html -->
<dx-data-grid id="gridContainer">
<dxo-column-chooser [enabled]="true"></dxo-column-chooser>
<dxo-toolbar>
<dxi-item location="after">
<dx-button
icon="refresh"
(onClick)="refreshDataGrid($event)">
</dx-button>
</dxi-item>
<dxi-item name="columnChooserButton"></dxi-item>
</dxo-toolbar>
</dx-data-grid>
// app.component.ts
// ...
import {
DxDataGridModule,
DxDataGridComponent
} from "devextreme-angular/ui/data-grid";
import { DxButtonModule } from "devextreme-angular/ui/button";
@Component({
// ...
})
export class AppComponent {
@ViewChild(DxDataGridComponent, { static: false }) dataGrid: DxDataGridComponent;
refreshDataGrid() {
this.dataGrid.instance.refresh();
}
}
Remove or Rearrange Toolbar Items
If you declare a custom items array, the default array will be overridden. You can leverage this behavior to remove a toolbar item (do not include it in the custom array).
Toolbar items within the UI preserve the order in which they are declared. If you wish to rearrange toolbar items, simply modify their declaration order. You can also control the location wherein a toolbar item appears (the
location property specifies the location of a toolbar item within the toolbar itself). In the following sample, the
location property is used to move the Search Panel to the left side of the toolbar:
React
export default function App() {
return (
<DataGrid>
<ColumnChooser enabled={true} />
<SearchPanel visible={true} />
<Editing allowAdding={true} allowUpdating={true} allowDeleting={true} />
<Toolbar>
<Item name="searchPanel" location="before" />
<Item name="columnChooserButton" />
<Item name="addRowButton" />
</Toolbar>
</DataGrid>
);
}
Customize Predefined Toolbar Items
If you do not wish to define toolbar items from scratch, you can customize predefined items with the
options property. This property accepts the configuration of a DevExtreme component used as the toolbar item. For instance, to customize the Add Row button, use DevExtreme
Button properties; for the Export button, use
DropDownButton properties, etc. The following code overrides the
onClick event handler of the Add Row button and adds a custom item to the Export drop-down menu. Note that the Export menu
items array contains
undefined entries. They are used as placeholders for default menu commands.
React
export default function App() {
const dataGridRef = useRef();
const addRowButtonOptions = useMemo(() => {
return {
onClick() {
dataGridRef.current.instance.addRow();
notify("Add Row was clicked");
}
};
}, []);
const exportButtonOptions = useMemo(() => {
return {
items: [
undefined,
undefined,
{
icon: "export",
text: "Export to CSV",
onClick() {
notify("Export to CSV was selected");
}
}
]
};
}, []);
return (
<DataGrid
ref={dataGridRef}>
<Editing allowAdding={true} allowUpdating={true} allowDeleting={true} />
<Export enabled={true} allowExportSelectedData={true} />
<Toolbar>
<Item name="addRowButton" options={addRowButtonOptions} />
<Item name="exportButton" options={exportButtonOptions} />
</Toolbar>
</DataGrid>
);
}
Disable/Enable a Toolbar Item
Toolbar items include a
disabled property. You can use this property to control user interaction with individual toolbar items (whether the toolbar item responds to a click).
Vue
<template>
<DxDataGrid>
<DxColumnChooser :enabled="true" />
<DxSearchPanel :visible="true" />
<DxToolbar>
<DxItem name="columnChooserButton" :disabled="isColumnChooserDisabled" />
<DxItem name="searchPanel" />
</DxToolbar>
</DxDataGrid>
<DxCheckBox
text="Disable the Column Chooser Button"
v-model="isColumnChooserDisabled"
/>
</template>
<script>
// ...
export default {
// ...
data() {
return {
isColumnChooserDisabled: true
};
}
};
</script>
Hide/Display the Toolbar
To control toolbar visibility, use the
visible property.
Angular
<!-- app.component.html -->
<dx-data-grid>
<!-- … -->
<dxo-toolbar [visible]="isToolbarVisible"></dxo-toolbar>
</dx-data-grid>
<dx-check-box
text="Display the Toolbar"
[(value)]="isToolbarVisible">
</dx-check-box>
// app.component.ts
// …
export class AppComponent {
isToolbarVisible: boolean = true;
// ...
}
Your Feedback Matters
As always, we welcome your thoughts and feedback. Let us know what you think of our new Toolbar Customization API. Feel free to leave a comment below or contact us via the DevExpress Support Center.
Free DevExpress Products - Get Your Copy Today
The following free DevExpress product offers remain available. Should you have any questions about the free offers below, please submit a ticket via the
DevExpress Support Center at your convenience. We'll be happy to follow-up.