Devexpress Blazor Toolbar

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 |

# Install from NuGet.org:
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 ``:

@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

1. Render mode: InteractiveServer, InteractiveWebAssembly, InteractiveAuto, or static SSR? (Static SSR limits interactivity.)
2. New or existing project?
3. Item mode: Unbound (declare items inline) or bound (bind to a data collection)?
4. Features needed: Drop-downs? Checked/radio items? Adaptivity? Icon-only items? Form submission?
5. 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


    
    
    

Documentation & Navigation Guide

Getting Started

📄 [references/getting-started.md](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](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](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](examples/quickstart.razor)

More Examples

| File | What it demonstrates | |---|---| | 📄 [examples/data-bound.razor](examples/data-bound.razor) | Data-bound toolbar with hierarchical items and ItemClick handler | | 📄 [examples/split-dropdown.razor](examples/split-dropdown.razor) | Split drop-down buttons (separate main action + drop-down arrow) | | 📄 [examples/adaptive-toolbar.razor](examples/adaptive-toolbar.razor) | Adaptive layout: icon collapse, overflow menu, AdaptivePriority |

@page "/toolbar-demo"
@rendermode InteractiveServer
@using DevExpress.Blazor


    
        
        
        
        
        
        
        
            
                
                
                
            
        
        
    


Alignment: @GetAlignment()

@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 | 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 ` 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 | 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 | 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 ` 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 | Custom markup for the item's inner content area while preserving the default button chrome, border, icon, and drop-down button | | Template | RenderFragment | 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

Pattern 2: Checked / Radio Items

    
    
    


@code {
    bool ShowPanel { get; set; } = true;
    bool SortAscending { get; set; } = true;
    bool SortDescending { get; set; } = false;
}

Pattern 3: Adaptivity

Troubleshooting

| Symptom | Likely Cause | Fix | |---|---|---| | Component renders without styles | App.razor missing theme/scripts registration | Add @DxResourceManager.RegisterTheme(Themes.Fluent) and @DxResourceManager.RegisterScripts() inside ` 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(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 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

1. 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.
2. Build verification: Run dotnet build after changes and fix errors before reporting success.
3. Render mode: Most Toolbar interactivity (clicks, checked state) requires an interactive render mode.
4. GroupName for radio behavior: Items in the same GroupName act as a radio group — only one can be checked.
5. Obsolete property: ItemSizeMode is obsolete — use SizeMode instead. Do not generate ItemSizeMode.
6. Version consistency: All DevExpress packages must use the same version number.
7. License: A valid DevExpress license is required.
8. No destructive changes: Preserve existing using statements and class structure.
9. 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 ``. Without them the component renders without styles.
10. 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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DevExpress
• Source: DevExpress/agent-skills
• License: MIT
• Homepage: https://www.devexpress.com

Install and usage instructions live in the source repository linked above.