# Devexpress Blazor Toolbar

> 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, DxTool…

- **Type:** Skill
- **Install:** `agentstack add skill-devexpress-agent-skills-devexpress-blazor-toolbar`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DevExpress](https://agentstack.voostack.com/s/devexpress)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DevExpress](https://github.com/DevExpress)
- **Source:** https://github.com/DevExpress/agent-skills/tree/main/plugins/dx-blazor/skills/devexpress-blazor-toolbar
- **Website:** https://www.devexpress.com

## Install

```sh
agentstack add skill-devexpress-agent-skills-devexpress-blazor-toolbar
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 |

```bash
# 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:
```csharp
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 ``:
```razor
@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:
```razor
@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

```razor
@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 |

```razor
@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

```razor

    
        
            
                
                
                
            
        
        
            
                
                
                
            
        
    

```

### Pattern 2: Checked / Radio Items

```razor

    
    
    


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

### Pattern 3: Adaptivity

```razor

    
        
        
        
    

```

## 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

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

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-devexpress-agent-skills-devexpress-blazor-toolbar
- Seller: https://agentstack.voostack.com/s/devexpress
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.