Devexpress Blazor Combobox

DevExpress Blazor ComboBox

DxComboBox 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, IQueryable, 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 ``
• Use virtual scrolling for large lists

Prerequisites & Installation

NuGet Package

| Package | Purpose | |---|---| | DevExpress.Blazor | ComboBox + all standard Blazor UI components |

# 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

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 (or primitive), a list of custom objects, an IQueryable, 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)?
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 *@


@code {
    IEnumerable Cities = new List { "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

| Topic | Reference File | When to load | |-------|---------------|--------------| | Getting Started (setup, first ComboBox) | [references/getting-started.md](references/getting-started.md) | New project setup or first-time use | | Data Binding (simple, custom objects, async, virtual scroll) | [references/data-binding.md](references/data-binding.md) | Binding to data or setting Value | | Search, Filter, Grouping, Disabled Items | [references/data-shaping.md](references/data-shaping.md) | Configuring search or grouping | | Multiple Columns | [references/multiple-columns.md](references/multiple-columns.md) | Multi-column drop-down layout | | Appearance Customization & Templates | [references/appearance-and-templates.md](references/appearance-and-templates.md) | Styling, size modes, templates | | Buttons & Cascading | [references/buttons-and-cascading.md](references/buttons-and-cascading.md) | Clear button, custom buttons, cascading ComboBoxes | | Validation | [references/validation.md](references/validation.md) | `` integration |

Key Properties & API Surface

DxComboBox — most-used members

| Property / Event | Type | Description | |---|---|---| | Data | IEnumerable | Binds the drop-down list to a data source | | DataAsync | Func>> | Asynchronous data loading | | Value / @bind-Value | TValue | Selected value; use @bind-Value for two-way binding | | ValueChanged | EventCallback | Fired when the value changes | | TextFieldName | string | Field name to display as item text (for custom object collections) | | KeyFieldName | string | Field used as the item key (decouples TData from TValue) | | KeyFieldNames | string[] | Multiple key fields for composite keys | | GroupFieldName | string | Field used to group items in the list | | DisabledFieldName | string | Boolean field that marks items as disabled | | NullText | string | Placeholder displayed when value is null | | ClearButtonDisplayMode | DataEditorClearButtonDisplayMode | Controls Clear button visibility (Auto, Always, Never) | | ShowDropDownButton | bool | Shows/hides the built-in drop-down toggle button | | AllowUserInput | bool | Allows typing a custom value not in the list | | SearchMode | ListSearchMode | AutoSearch (default), Disabled | | SearchFilterCondition | ListSearchFilterCondition | Contains, StartsWith, Equals | | SearchTextParseMode | ListSearchTextParseMode | How multiple words are combined | | SearchDelay | int | Debounce delay (ms) before search fires | | EditFormat | string | Format string for the edit box value in multi-column mode | | DropDownDirection | DropDownDirection | Down (default), Up | | DropDownWidthMode | DropDownWidthMode | ContentOrEditorWidth (default), ContentWidth, EditorWidth | | SizeMode | SizeMode | Small, Medium (default), Large | | DataLoadMode | ListDataLoadMode | Auto (default), OnDemand | | ListRenderMode | ListRenderMode | Default, Virtual (virtual scrolling) | | InputCssClass | string | CSS class applied to the input element | | InputId | string | HTML id of the input element (for label association) | | ItemDisplayTemplate | RenderFragment> | Customises drop-down item rendering | | EditBoxDisplayTemplate | RenderFragment> | Customises selected-value rendering in the edit box | | ColumnCellDisplayTemplate | RenderFragment> | Customises all column cells in multi-column mode | | ValidateBy | ComboBoxValidateBy | Text or Value — which property is validated |

DxListEditorColumn — for multi-column drop-down

| Property | Type | Description | |---|---|---| | FieldName | string | Data source field for this column | | Caption | string | Column header text | | Width | string | Column width (CSS value, e.g. "50px") | | SearchEnabled | bool | Include this column in search operations | | CellDisplayTemplate | RenderFragment> | Per-column cell template |

Enums

| Enum | Values | |---|---| | DataEditorClearButtonDisplayMode | Auto, Always, Never | | ListSearchMode | AutoSearch, Disabled | | ListSearchFilterCondition | Contains, StartsWith, Equals | | ListDataLoadMode | Auto, OnDemand | | ListRenderMode | Default, Virtual | | DropDownDirection | Down, Up | | DropDownWidthMode | ContentOrEditorWidth, ContentWidth, EditorWidth | | SizeMode | Small, Medium, Large |

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):

@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

Pattern 3 — Multi-Column Drop-Down

Troubleshooting

| Symptom | Likely Cause | Fix | |---|---|---| | Drop-down doesn't open / events don't fire | Static SSR render mode | Add @rendermode InteractiveServer (or WASM/Auto) to the page or component | | Selected item not highlighted in drop-down | Custom object without Equals/GetHashCode, or different TData/TValue | Override Equals/GetHashCode, or use KeyFieldName to decouple types | | Items show ClassName instead of text | TextFieldName not set for custom object collection | Set TextFieldName to the display field name | | Search doesn't filter | SearchMode defaults to AutoSearch but AllowUserInput blocks it | Verify SearchMode="ListSearchMode.AutoSearch" is set; check AllowUserInput | | ValueChanged doesn't update cascade list | Using @bind-Value instead of Value + ValueChanged separately | Use Value="@val" ValueChanged="@(v => HandleChange(v))" for cascading | | Drop-down direction wrong | Default DropDownDirection.Down | Set DropDownDirection="DropDownDirection.Up" if at the bottom of the page | | Virtual scrolling item missing | ListRenderMode.Virtual + DataLoadMode.OnDemand limitation | Known limitation: selected item outside viewport may not scroll into view | | "DxComboBox requires a value for the 'Expression' property" in EditForm | Editor not using two-way binding | Replace Value="@val" with @bind-Value="@val", or explicitly set ValueExpression="@(() => val)" | | "The type arguments cannot be inferred from the usage" for DataAsync | Wrong function signature for async data loading | Ensure the function returns Task> and accepts a CancellationToken parameter | | "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 |

Constraints & Rules

CRITICAL: Follow these rules in every interaction:

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 DxComboBox 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: After making changes, always run dotnet build and check for errors before reporting success.
3. NuGet packages: Use only DevExpress.Blazor. Do not guess alternative package names.
4. Namespace imports: Always include @using DevExpress.Blazor in _Imports.razor or the component file.
5. Version consistency: All DevExpress packages in a project must use the same version. Do not mix versions.
6. License: DevExpress requires a valid license. Remind the user if they encounter license-related build errors.
7. No destructive changes: Preserve existing using statements, class structure, and unrelated code. Only add or modify what is necessary.
8. Interactivity: DxComboBox requires an interactive render mode. If the page uses Static SSR, add @rendermode InteractiveServer (or appropriate mode) to the page or a parent component.
9. Custom objects: When TData is a custom class and TData == TValue, the class must override Equals and GetHashCode for item selection to work correctly. Alternatively, use KeyFieldName to avoid this requirement.

Using DevExpress Documentation MCP

If the DevExpress Docs MCP server is available (check for devexpress_docs_search and devexpress_docs_get_content tools), use it to supplement this skill:

1. Search for documentation: devexpress_docs_search(technology="Blazor", query="ComboBox ")
2. Fetch full content: devexpress_docs_get_content(url="")

When to use MCP vs. built-in references:

• Use built-in references for: Getting started, common patterns, key properties covered in this skill.
• Use MCP for: Advanced scenarios, version-specific API changes, features not covered here, or when you need exact method signatures.
• Always prefer MCP for: Confirming event argument types, enum values, or interface members you are not 100% certain about.

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.