devexpress/agent-skills/devexpress-blazor-ribbon

DevExpress Blazor Ribbon

DxRibbon is a tabbed command bar for Blazor applications. It organizes commands in tabs and groups — following an Office-style UX. The Ribbon supports standard items, toggle items, color palettes, combo boxes, spin editors, and contextual tabs that appear only when contextually relevant.

When to Use This Skill

• Add an Office-style ribbon to a Blazor page
• Create tabs (Home, Insert, Format, etc.) with groups and commands
• Add an Application tab (File menu) with nested sub-items
• Show contextual tabs only when certain content is selected (e.g., Picture Format, Table Tools)
• Create toggle and radio-group items in the ribbon
• Add color palette pickers to the ribbon
• Embed combo boxes and spin editors in ribbon groups
• Integrate the Ribbon with other components (RichEdit, Grid)

Prerequisites & Installation

NuGet Package

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

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

1. Render mode: InteractiveServer, InteractiveWebAssembly, InteractiveAuto, or static SSR?
2. New or existing project?
3. Tabs: What tabs and groups are needed?
4. Application tab: Is a File/Application menu required?
5. Contextual tabs: Do any tabs appear conditionally (e.g., table tools, picture format)?
6. Special items: Color palette? Combo box? Spin editor? Toggle items?

Rule: Ribbon interactivity (clicks, toggles) requires an interactive render mode.

Component Overview

DxRibbon provides:

• Tabbed structure: DxRibbonTab → DxRibbonGroup → items (hierarchical command organization)
• Application tab: DxRibbonApplicationTab — a special "File" button with a nested item menu
• Item types: DxRibbonItem, DxRibbonToggleItem, DxRibbonToggleGroup, DxRibbonComboBoxItem<T,V>, DxRibbonSpinEditItem<T>, DxRibbonColorPaletteItem, DxRibbonColorGroup
• Contextual tabs: DxRibbonTab with Contextual="true" and Visible="@condition" — appear only when needed

Core Entry Point (Minimal)

@using DevExpress.Blazor
 
<DxRibbon>
    <DxRibbonTab Text="Home">
        <DxRibbonGroup>
            <DxRibbonItem Text="Command" />
        </DxRibbonGroup>
    </DxRibbonTab>
</DxRibbon>

Documentation & Navigation Guide

Getting Started

📄 references/getting-started.md

When you need to:

• Install the package and add DxRibbon to a page
• Create a complete minimal ribbon (tabs, groups, items)
• Add an Application tab (File menu)

Structure and Items

📄 references/structure-and-items.md

When you need to:

• Understand ribbon structure (Application tab → Tabs → Groups → Items)
• Use toggle items or radio-group toggle items
• Add combo boxes, spin editors, or color palettes to ribbon groups
• Add icons and tooltips to ribbon items

Contextual and Advanced

📄 references/contextual-and-advanced.md

When you need to:

• Show/hide contextual tabs based on selection
• Implement split drop-down buttons
• Programmatically select a tab
• Bind ribbon items to application state

Quick Start Example

📄 examples/quickstart.razor

More Examples

@page "/ribbon-demo"
@rendermode InteractiveServer
@using DevExpress.Blazor
 
<DxRibbon>
    <DxRibbonApplicationTab Text="File">
        <DxRibbonApplicationTabItem Text="New" />
        <DxRibbonApplicationTabItem Text="Open" />
        <DxRibbonApplicationTabItem Text="Save" />
        <DxRibbonApplicationTabItem Text="Save As">
            <DxRibbonApplicationTabItem Text="PDF (.pdf)" />
            <DxRibbonApplicationTabItem Text="Plain Text (.txt)" />
        </DxRibbonApplicationTabItem>
    </DxRibbonApplicationTab>
    <DxRibbonTab Text="Home">
        <DxRibbonGroup>
            <DxRibbonItem Text="Cut" />
            <DxRibbonItem Text="Copy" />
            <DxRibbonItem Text="Paste" />
        </DxRibbonGroup>
        <DxRibbonGroup>
            <DxRibbonToggleGroup>
                <DxRibbonToggleItem Text="Bold"   @bind-Checked="IsBold" />
                <DxRibbonToggleItem Text="Italic" @bind-Checked="IsItalic" />
            </DxRibbonToggleGroup>
            <DxRibbonComboBoxItem Data="@FontSizes"
                                  @bind-Value="CurrentFontSize"
                                  NullText="Font Size"
                                  Width="100px" />
        </DxRibbonGroup>
    </DxRibbonTab>
    <DxRibbonTab Text="Picture Format" Contextual="true" Visible="@ImageSelected">
        <DxRibbonGroup>
            <DxRibbonItem Text="Crop" />
            <DxRibbonItem Text="Resize" />
        </DxRibbonGroup>
    </DxRibbonTab>
</DxRibbon>
 
@code {
    bool IsBold       { get; set; } = false;
    bool IsItalic     { get; set; } = false;
    bool ImageSelected { get; set; } = false;
    int? CurrentFontSize { get; set; }
 
    List<int> FontSizes = new() { 8, 10, 12, 14, 16, 18, 24, 36 };
}

Key Properties & API Surface

DxRibbon

DxRibbonApplicationTab

Important: DxRibbonApplicationTab must use open/close tags, not a self-closing tag. Child DxRibbonApplicationTabItem elements placed between the tags are rendered as the drop-down menu. A self-closing <DxRibbonApplicationTab /> produces an empty menu.

Child items: DxRibbonApplicationTabItem (nestable for submenus).

DxRibbonTab

DxRibbonGroup

Container for ribbon items. Groups can collapse into labeled drop-down buttons during adaptive resize — use Text and IconCssClass to define the collapsed button appearance.

DxRibbonItem

DxRibbonToggleItem / DxRibbonToggleGroup

DxRibbonToggleGroup wraps DxRibbonToggleItem components. Items in the same group act as radio buttons — only one can be checked at a time.

DxRibbonComboBoxItem (TData, TValue)

DxRibbonSpinEditItem (T)