devexpress/agent-skills/devexpress-blazor-combobox

DevExpress Blazor ComboBox

DxComboBox<TData, TValue> is a text editor with a searchable drop-down list. It binds to strongly-typed collections or custom objects, supports multi-column layouts, grouping, virtual scrolling, cascading dropdowns, and fully customizable item and edit-box templates.

When to Use This Skill

• Add a single-selection dropdown or selector to a Blazor form
• Bind to any IEnumerable<T>, IQueryable<T>, or async collection
• Enable live search/filter as the user types
• Display grouped items with a group header
• Create cascading (dependent) dropdowns
• Show multiple columns in the drop-down list
• Customise item rendering via ItemDisplayTemplate or EditBoxDisplayTemplate
• Add a Clear button, custom command buttons, or placeholder text
• Validate ComboBox selection inside a standard <EditForm>
• Use virtual scrolling for large lists

Prerequisites & Installation

NuGet Package

# Install from NuGet.org:
dotnet add package DevExpress.Blazor

Setup (existing project)

1. Register DevExpress services in Program.cs:

``csharp builder.Services.AddDevExpressBlazor(); ` > **v26.1 note**: DevExpress.Blazor no longer includes options.BootstrapVersion or DevExpress.Blazor.BootstrapVersion`. Do not generate either API.

1. Apply a theme and add client scripts in App.razor:

``razor @DxResourceManager.RegisterTheme(Themes.Fluent) @DxResourceManager.RegisterScripts() ``

1. Add the namespace to _Imports.razor:

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

Ask these questions before generating code:

1. Render mode: Are you using InteractiveServer, InteractiveWebAssembly, or InteractiveAuto? (DxComboBox does not function in Static SSR.)
2. Is this a new project or an existing one? New projects can use the DevExpress Template Kit; existing ones need manual setup above.
3. Data type: Are you binding to a simple IEnumerable<string> (or primitive), a list of custom objects, an IQueryable<T>, or loading data asynchronously?
4. Value type: Is the bound Value the same type as the data items (TData == TValue) or a different key type (e.g., int ID from a List<Product>)?
5. Custom objects: If binding to custom objects, have you overridden Equals and GetHashCode in your model? (Required for correct item matching.)
6. Features needed: Do you need search/filter, grouping, multiple columns, cascading, templates, or validation?

Component Overview

@* Minimal example: string list *@
<DxComboBox Data="@Cities"
            @bind-Value="@SelectedCity"
            NullText="Select a city…"
            ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto" />
 
@code {
    IEnumerable<string> Cities = new List<string> { "London", "Berlin", "Paris" };
    string SelectedCity { get; set; }
}

Key generic parameters:

• TData — the type of items in the Data collection
• TValue — the type of the bound Value; equals TData when binding to the whole object

Documentation & Navigation Guide

Key Properties & API Surface

DxComboBox<TData, TValue> — most-used members

DxListEditorColumn — for multi-column drop-down

Enums

Common Patterns

Pattern 1 — Bind to a Custom Object Collection

When TData is a custom class, set TextFieldName, and override Equals/GetHashCode in the model (or use KeyFieldName to avoid this):

<DxComboBox Data="@Staff.DataSource"
            TextFieldName="@nameof(Person.Text)"
            @bind-Value="@SelectedPerson" />
 
@code {
    Person SelectedPerson { get; set; } = Staff.DataSource[0];
}

Model requirement when TData == TValue:

public class Person {
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Text => $"{FirstName} {LastName}";
 
    public override bool Equals(object obj) =>
        obj is Person p && Id == p.Id;
 
    public override int GetHashCode() => HashCode.Combine(Id);
}

Pattern 2 — Search & Filter with Group Data

<DxComboBox Data="@Customers"
            @bind-Value="@SelectedCustomer"
            TextFieldName="@nameof(Customer.ContactName)"
            GroupFieldName="@nameof(Customer.Country)"
            SearchMode="ListSearchMode.AutoSearch"
            SearchFilterCondition="ListSearchFilterCondition.Contains" />

Pattern 3 — Multi-Column Drop-Down

<DxComboBox Data="@Staff.DataSource"
            @bind-Value="@SelectedPerson"
            EditFormat="{1} {2}">
    <Columns>
        <DxListEditorColumn FieldName="Id" Width="50px" />
        <DxListEditorColumn FieldName="FirstName" Caption="Name" />
        <DxListEditorColumn FieldName="LastName" Caption="Surname" />
    </Columns>
</DxComboBox>

Troubleshooting