| name | devexpress-blazor-toolbar |
| description | Build and configure the DevExpress Blazor Toolbar (DxToolbar) — an adaptive command bar for Blazor apps. Use when adding toolbars/command bars, configuring DxToolbarItem buttons, drop-down menus, overflow/adaptivity, icons/tooltips/links, checked and radio-group items, data binding, item templates (ChildContent/Template), and triggering actions like form submission. Also use for DxToolbar, DxToolbarItem, adaptive toolbar, overflow menu, command bar, and toolbar feature comparisons or migration scenarios. |
| compatibility | Requires .NET 8.0, 9.0, or 10.0. Interactive render mode required for interactivity (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto). NuGet package DevExpress.Blazor is available on NuGet.org. A valid DevExpress license is required. |
| metadata | {"author":"DevExpress","version":"26.1","source-commit":"8493730c9e9a47a009fc307a37c307e157663819"} |
DevExpress Blazor Toolbar
DxToolbar is an adaptive button-based command bar for Blazor applications. It displays frequently used actions as buttons, drop-downs, checked items, and icon groups. The Toolbar adapts its layout automatically when the container width changes — collapsing items to icons or moving them into an overflow submenu.
When to Use This Skill
- Add a toolbar with action buttons to a Blazor page or layout
- Create drop-down item lists (sub-menu, modal dialog, or bottom sheet)
- Implement checked items and radio-group button behavior
- Bind the Toolbar to flat or hierarchical data collections
- Customize item appearance with render styles and templates
- Align items to the left or right
- Configure adaptive behavior for different screen widths
- Group items visually with separators
- Submit a form on a toolbar button click
- Add icons, tooltips, and navigation links to toolbar items
Prerequisites & Installation
NuGet Package
| Package | Purpose |
|---|
DevExpress.Blazor | Toolbar component and all core Blazor UI controls |
dotnet add package DevExpress.Blazor
Important: All DevExpress packages must use the same version. A valid DevExpress license is required.
Required Registration (all three steps must be present)
Program.cs — register DevExpress services:
builder.Services.AddDevExpressBlazor();
v26.1 note: DevExpress.Blazor no longer includes options.BootstrapVersion or DevExpress.Blazor.BootstrapVersion. Do not generate either API.
Components/App.razor — register theme and client scripts inside <head>:
@using DevExpress.Blazor
@DxResourceManager.RegisterTheme(Themes.Fluent)
@DxResourceManager.RegisterScripts()
Without these two calls components render without styles and client interactivity is broken.
Components/_Imports.razor — add global namespace:
@using DevExpress.Blazor
Before You Start — Ask the Developer
- Render mode:
InteractiveServer, InteractiveWebAssembly, InteractiveAuto, or static SSR? (Static SSR limits interactivity.)
- New or existing project?
- Item mode: Unbound (declare items inline) or bound (bind to a data collection)?
- Features needed: Drop-downs? Checked/radio items? Adaptivity? Icon-only items? Form submission?
- Styling: Default, Contained, or Plain render style?
Rule: If interactivity (item clicks, checked states) is required, the page or component must use an interactive render mode.
Component Overview
DxToolbar provides:
- Unbound mode: Items declared as
DxToolbarItem components between DxToolbar tags (DxToolbarItem)
- Bound mode: Items loaded from a data collection via the
Data property and DxToolbarDataMapping (DxToolbar.Data)
- Drop-down items: Each
DxToolbarItem can have child Items rendered as a sub-menu, modal dialog, or bottom sheet
- Checked items: Use
GroupName to create toggle or radio-group buttons (DxToolbarItem.GroupName, @bind-Checked)
- Adaptivity: Automatically hides item text or moves items to an overflow menu when space is limited
Core Entry Point
@using DevExpress.Blazor
<DxToolbar>
<DxToolbarItem Text="Save" IconCssClass="oi oi-cloud-upload" />
<DxToolbarItem Text="Open" IconCssClass="oi oi-folder" />
<DxToolbarItem IconCssClass="oi oi-cog"
Alignment="ToolbarItemAlignment.Right"
BeginGroup="true" />
</DxToolbar>
Documentation & Navigation Guide
Getting Started
📄 references/getting-started.md
When you need to:
- Install the package and add a Toolbar to a page
- Understand unbound vs. bound modes
- See a minimal working example
Items and Interactions
📄 references/items-and-interactions.md
When you need to:
- Add drop-down sub-menus to toolbar items
- Create checked items or radio-group buttons
- Handle item click events
- Add navigation links, tooltips, and icons to items
- Use
ChildContent for custom inner markup or Template to replace the entire item
- Submit a form from a toolbar button
Adaptivity and Appearance
📄 references/adaptivity-and-appearance.md
When you need to:
- Configure adaptive layout (hide text, move items to submenu)
- Apply render styles (Contained, Plain)
- Set item size mode
- Bind items to a data collection
- Customize the toolbar title
Quick Start Example
📄 examples/quickstart.razor
More Examples
@page "/toolbar-demo"
@rendermode InteractiveServer
@using DevExpress.Blazor
<DxToolbar Title="Text Editor">
<Items>
<DxToolbarItem Text="New" IconCssClass="oi oi-file" Click="OnNew" />
<DxToolbarItem Text="Open" IconCssClass="oi oi-folder" Click="OnOpen" />
<DxToolbarItem Text="Save" IconCssClass="oi oi-cloud-upload" Click="OnSave"
BeginGroup="true" />
<DxToolbarItem GroupName="align" IconCssClass="oi oi-align-left"
BeginGroup="true" @bind-Checked="AlignLeft" />
<DxToolbarItem GroupName="align" IconCssClass="oi oi-align-center"
@bind-Checked="AlignCenter" />
<DxToolbarItem GroupName="align" IconCssClass="oi oi-align-right"
@bind-Checked="AlignRight" />
<DxToolbarItem Text="Format" BeginGroup="true">
<Items>
<DxToolbarItem Text="Bold" />
<DxToolbarItem Text="Italic" />
<DxToolbarItem Text="Underline" />
</Items>
</DxToolbarItem>
<DxToolbarItem IconCssClass="oi oi-cog"
Alignment="ToolbarItemAlignment.Right" />
</Items>
</DxToolbar>
<p>Alignment: @GetAlignment()</p>
@code {
bool AlignLeft { get; set; } = true;
bool AlignCenter { get; set; } = false;
bool AlignRight { get; set; } = false;
void OnNew() => Console.WriteLine("New clicked");
void OnOpen() => Console.WriteLine("Open clicked");
void OnSave() => Console.WriteLine("Save clicked");
string GetAlignment() =>
AlignLeft ? "Left" : AlignCenter ? "Center" : "Right";
}
What This Does
Renders a toolbar with file action buttons, a radio-group alignment selector, a drop-down Format menu, and a right-aligned settings icon. Clicking alignment buttons updates the AlignLeft/Center/Right state.
Key Properties & API Surface
DxToolbar
| Property | Type | Description |
|---|
Title | string | Text displayed at the left of the toolbar |
TitleTemplate | RenderFragment<string> | Custom template for the title area |
Items | RenderFragment | Slot for DxToolbarItem components (unbound mode) |
Data | object | Data collection for bound mode |
DataMappings | RenderFragment | Slot for DxToolbarDataMapping in bound mode — place <DataMappings><DxToolbarDataMapping .../></DataMappings> inside DxToolbar |
ItemRenderStyleMode | ToolbarRenderStyleMode | Contained or Plain fill mode for all items |
SizeMode | SizeMode | Item size: Small, Medium (default), Large |
DropDownDisplayMode | DropDownDisplayMode | DropDown, ModalDialog, or ModalBottomSheet |
DropDownMaxHeight | string | Limits the maximum height of all drop-down lists (CSS unit string, e.g., "200px"). Only applies when DropDownDisplayMode is DropDown. |
DropDownCssClass | string | CSS class applied to all drop-down panels — use for custom width, padding, etc. |
Target | string | Default HTML target attribute for all NavigateUrl items (e.g., "_blank") — overridden per item by DxToolbarItem.Target |
AdaptivityAutoCollapseItemsToIcons | bool | Hides text for icon items when space is limited |
AdaptivityAutoHideRootItems | bool | Moves root items to overflow submenu when space is limited |
AdaptivityMinRootItemCount | int | Minimum root items to keep visible before hiding |
ItemClick | EventCallback<ToolbarItemClickEventArgs> | Global click handler for all items — use args.ItemName to identify the clicked item; requires Name to be set on each DxToolbarItem |
DxToolbarItem
| Property | Type | Description |
|---|
Text | string | Item label |
IconCssClass | string | CSS class for the item icon |
IconUrl | string | URL of an image to use as the item icon — alternative to IconCssClass |
GroupName | string | Groups items as toggle buttons; same group = radio behavior |
@bind-Checked | bool | Two-way binding for checked state |
Alignment | ToolbarItemAlignment | Default (left) or Right |
BeginGroup | bool | Inserts a visual separator before this item |
NavigateUrl | string | Makes the item a navigation link |
Click | EventCallback<ToolbarItemClickEventArgs> | Click event handler |
RenderStyle | ButtonRenderStyle | Item color style (e.g., Info, Success, Danger) |
RenderStyleMode | ButtonRenderStyleMode | Overrides the toolbar-level ItemRenderStyleMode for this item |
CssClass | string | CSS class applied to the item element (e.g., custom background, border) |
DropDownDisplayMode | DropDownDisplayMode | Per-item override of the toolbar-level drop-down mode (DropDown, ModalDialog, ModalBottomSheet); Auto inherits from DxToolbar.DropDownDisplayMode. Root items only. |
DropDownCssClass | string | CSS class for this item's drop-down panel (e.g., custom width) |
SubmitFormOnClick | bool | When true, clicking the item submits the parent EditForm. Place DxToolbar inside <EditForm> and set this on the submit button item. |
AdaptivePriority | int | Order in which items are hidden during adaptivity (lower = hidden first) |
AdaptiveText | string | Alternative text shown in the overflow submenu |
Tooltip | string | Tooltip text shown on hover |
Items | RenderFragment | Child items (creates a drop-down menu) |
ChildContent | RenderFragment<IToolbarItemInfo> | Custom markup for the item's inner content area while preserving the default button chrome, border, icon, and drop-down button |
Template | RenderFragment<IToolbarItemInfo> | Replaces the entire item content, including the default text, icon area, border styling, and drop-down button |
Name | string | Unique item identifier — required when using DxToolbar.ItemClick to identify which item was clicked via args.ItemName |
Enabled | bool | Whether the item is interactive |
Visible | bool | Whether the item is visible |
SplitDropDownButton | bool | Splits a parent item into a main action button + separate drop-down arrow |
@bind-DropDownVisible | bool | Programmatically opens or closes the item's drop-down |
DropDownCaption | string | Title shown in the modal header when DropDownDisplayMode is ModalDialog or ModalBottomSheet (defaults to item Text) |
CloseMenuOnClick | bool? | Controls whether the parent sub-menu closes when this item is clicked. Defaults: regular items close, checked/templated items stay open. Set true to force close, false to keep open. |
Target | string | HTML target attribute for NavigateUrl links (e.g., "_blank" to open in a new tab) |
ToolbarItemClickEventArgs
| Property | Type | Description |
|---|
ItemName | string | The Name of the clicked DxToolbarItem |
Info | object | Internal item descriptor |
MouseEventArgs | MouseEventArgs | Browser mouse event data |
DxToolbarDataMapping
| Property | Type | Description |
|---|
Text | string | Data field for item text |
Key | string | Data field for unique item key |
ParentKey | string | Data field for parent item key (hierarchical data) |
Common Patterns
Pattern 1: Drop-Down Items
<DxToolbar DropDownDisplayMode="DropDownDisplayMode.DropDown">
<Items>
<DxToolbarItem Text="Font Style">
<Items>
<DxToolbarItem Text="Bold" />
<DxToolbarItem Text="Italic" />
<DxToolbarItem Text="Underline" />
</Items>
</DxToolbarItem>
<DxToolbarItem Text="Size" DropDownDisplayMode="DropDownDisplayMode.ModalDialog">
<Items>
<DxToolbarItem Text="8pt" />
<DxToolbarItem Text="10pt" />
<DxToolbarItem Text="12pt" />
</Items>
</DxToolbarItem>
</Items>
</DxToolbar>
Pattern 2: Checked / Radio Items
<DxToolbar>
<DxToolbarItem @bind-Checked="ShowPanel"
GroupName="ShowPanel"
Text="Show Panel" />
<DxToolbarItem BeginGroup="true"
@bind-Checked="SortAscending"
GroupName="SortOrder"
Text="Sort Ascending" />
<DxToolbarItem @bind-Checked="SortDescending"
GroupName="SortOrder"
Text="Sort Descending" />
</DxToolbar>
@code {
bool ShowPanel { get; set; } = true;
bool SortAscending { get; set; } = true;
bool SortDescending { get; set; } = false;
}
Pattern 3: Adaptivity
<DxToolbar AdaptivityAutoHideRootItems="true"
AdaptivityAutoCollapseItemsToIcons="true"
AdaptivityMinRootItemCount="2">
<Items>
<DxToolbarItem Text="Bold" IconCssClass="oi oi-bold"
AdaptivePriority="1" AdaptiveText="Bold" />
<DxToolbarItem Text="Italic" IconCssClass="oi oi-italic"
AdaptivePriority="1" AdaptiveText="Italic" />
<DxToolbarItem Text="Undo" IconCssClass="oi oi-action-undo"
AdaptivePriority="2" AdaptiveText="Undo" />
</Items>
</DxToolbar>
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|
| Component renders without styles | App.razor missing theme/scripts registration | Add @DxResourceManager.RegisterTheme(Themes.Fluent) and @DxResourceManager.RegisterScripts() inside <head> in App.razor |
| Item clicks not firing | Static SSR render mode | Add @rendermode InteractiveServer |
| Checked state not updating | Missing @bind-Checked | Use @bind-Checked instead of Checked |
| Drop-down not opening | Render mode is static | Ensure interactive render mode |
| Items overflow but no submenu | AdaptivityAutoHideRootItems not enabled | Set AdaptivityAutoHideRootItems="true" |
| Icon items show no text in submenu | Missing AdaptiveText | Set AdaptiveText on each item |
"Unhandled exception on the current circuit" with no detail | CircuitOptions.DetailedErrors not set | Add builder.Services.Configure<CircuitOptions>(o => o.DetailedErrors = true); in Program.cs (development only) |
"Component parameter 'ValueChanged' is used two or more times" compile error | @bind-Value and ValueChanged used together | Use @bind-Value="@val" for two-way binding, or Value="@val" ValueChanged="@handler" — never both simultaneously |
dx-blazor.js not found (404) behind a reverse proxy | Reverse proxy strips the app base path | Add app.UsePathBase("/subpath") before app.MapBlazorHub(), or set <base href="/subpath/" /> in App.razor |
Static assets return 404 (dx-blazor.css, dx-blazor.js) | UseStaticWebAssets() not called | Add app.UseStaticWebAssets(); in Program.cs before app.UseStaticFiles() |
"Could not find 'X' in 'window.DxBlazor'" JavaScript error | Stale browser-cached JS from an older DevExpress version | Hard-refresh the browser (Ctrl+Shift+R), clear site data, or verify all DevExpress NuGet packages are the same version |
"Cannot pass the parameter 'X' to component 'Y' with rendermode" | Non-serializable parameter passed across a render mode boundary | Move the component to a child .razor file with its own @rendermode directive; pass only serializable parameters |
| Custom text markup removes the item's border or drop-down arrow | Template replaces the entire item surface | Use ChildContent to customize only the text/content area and keep the built-in button chrome; reserve Template for full item replacement |
Constraints & Rules
- Never invent API: If a property, method, event, or feature is not documented in this skill or its references, do not assume it exists. When asked about an unfamiliar API, first try to verify it using the DevExpress documentation MCP (
devexpress_docs_search) or the local apidoc/ folder. Only after checking: if confirmed, use the API; if not found, explicitly state that it does not appear to be part of the DxToolbar API. Do not warn that a feature "may have been introduced in a recent version" as a way to justify inventing it.
- Build verification: Run
dotnet build after changes and fix errors before reporting success.
- Render mode: Most Toolbar interactivity (clicks, checked state) requires an interactive render mode.
- GroupName for radio behavior: Items in the same
GroupName act as a radio group — only one can be checked.
- Obsolete property:
ItemSizeMode is obsolete — use SizeMode instead. Do not generate ItemSizeMode.
- Version consistency: All DevExpress packages must use the same version number.
- License: A valid DevExpress license is required.
- No destructive changes: Preserve existing using statements and class structure.
- App.razor styles: When generating a new project or extending an existing one, always verify that
App.razor contains both @DxResourceManager.RegisterTheme(Themes.Fluent) and @DxResourceManager.RegisterScripts() inside <head>. Without them the component renders without styles.
- Template vs. ChildContent:
DxToolbarItem.Template replaces the entire item content, including built-in chrome such as the drop-down button. If the goal is to keep the default border, icon area, or drop-down arrow and only customize the inner text/content area, use DxToolbarItem.ChildContent instead.
Using DevExpress Documentation MCP
If the DevExpress Docs MCP server is available:
- Search:
devexpress_docs_search(technology="Blazor", query="DxToolbar data binding")
- Fetch:
devexpress_docs_get_content(url="https://docs.devexpress.com/Blazor/...")
Use MCP for exact property signatures, advanced scenarios, or features not covered in this skill.
