| name | devexpress-blazor-grid |
| description | Build and configure the DevExpress Blazor Grid (DxGrid) — a full-featured data grid for Blazor Server, WebAssembly, and Hybrid apps. Use when binding tabular data (IEnumerable/IQueryable/EF Core/server-mode/custom sources), enabling sorting/filtering/grouping/search, implementing CRUD editing (row/edit form/popup/cell), handling selection and focused rows, exporting to CSV/XLSX/PDF, customizing templates and summaries, and supporting large datasets with virtualization. Also use for DxGrid, DevExpress grid, Blazor data grid, virtual scrolling, server mode, and grid feature comparisons or migration scenarios. |
| compatibility | Requires .NET 8, 9, or 10. NuGet package DevExpress.Blazor is available on NuGet.org. A valid DevExpress license is required. Most features require an interactive render mode (InteractiveServer, InteractiveWebAssembly, or InteractiveAuto). |
| metadata | {"author":"DevExpress","version":"26.1","source-commit":"8493730c9e9a47a009fc307a37c307e157663819"} |
DevExpress Blazor Grid
DxGrid is a high-performance data grid for Blazor applications. It supports data binding to in-memory collections, Entity Framework Core, server-mode sources, and custom data sources. Key feature areas include sorting, grouping, filtering, multi-mode editing (edit row, edit form, popup, cell), row selection, data export (CSV/XLS/PDF), column templates, summaries, and drag-and-drop row reordering.
When to Use This Skill
- Display tabular data from any .NET data source in a Blazor page
- Implement CRUD operations (create, update, delete rows) with built-in edit forms
- Sort, group, filter, and search grid data in the UI or programmatically
- Export data to CSV, XLSX, or PDF with custom formatting
- Enable row selection (single or multiple) and act on selected data
- Add column chooser, resize, reorder, and freeze (pin) columns
- Use virtual scrolling for large in-memory datasets
- Bind to large remote datasets via EF Core server-mode sources
- Customize cell appearance using templates and
CustomizeElement
- Add a toolbar, context menu, or summary rows to the grid
Prerequisites & Installation
NuGet Package
| Package | Purpose |
|---|
DevExpress.Blazor | Grid + all standard Blazor UI components |
dotnet add package DevExpress.Blazor
Setup (existing project)
- Register DevExpress resources in
Program.cs:
builder.Services.AddDevExpressBlazor();
v26.1 note: DevExpress.Blazor no longer includes options.BootstrapVersion or DevExpress.Blazor.BootstrapVersion. Do not generate either API.
- Apply a theme and add client scripts in
App.razor inside <head>:
@using DevExpress.Blazor
@DxResourceManager.RegisterTheme(Themes.Fluent)
@DxResourceManager.RegisterScripts()
- Add the namespace to
_Imports.razor:
@using DevExpress.Blazor
Before You Start — Ask the Developer
Before generating code, ask:
- Render mode: Are you using
InteractiveServer, InteractiveWebAssembly, or InteractiveAuto? (Grid requires an interactive mode for sorting, filtering, editing, and paging.)
- Data source: Are you binding to a simple in-memory collection (
List<T>, IEnumerable<T>), EF Core (DbSet<T> or EntityInstantFeedbackSource), IQueryable<T>, or a custom data source (GridCustomDataSource)?
- Features needed: Do you need editing (which mode: EditRow, EditForm, PopupEditForm, EditCell)? Export? Selection? Virtual scrolling?
- Key field: Does your data model have a primary key property? (Required for editing, selection, and server-mode sources.)
- New or existing project?: Are you adding the grid to an existing project or starting fresh?
Ask before generating. Render mode and data source type significantly affect the code.
Component Overview
DxGrid provides:
- Data Binding (
Data, KeyFieldName): Binds to IEnumerable<T>, IListSource, IQueryable<T>, GridDevExtremeDataSource<T>, or GridCustomDataSource
- Column Types (
DxGridDataColumn, DxGridCommandColumn, DxGridSelectionColumn, DxGridBandColumn): Bound, unbound, command, selection, and band columns
- Data Shaping (
AllowSort, ShowGroupPanel, ShowSearchBox, FilterPanelDisplayMode): Sort, group, filter row, filter panel, search box
- Editing (
EditMode, EditModelSaving, DataItemDeleting): EditRow, EditForm, PopupEditForm, EditCell modes
- Selection (
SelectionMode, SelectedDataItems): Single and multiple row selection
- Export (
ExportToCsvAsync, ExportToXlsxAsync, ExportToPdfAsync): CSV, XLS/XLSX, and PDF export
- Paging & Scrolling (
PageSize, VirtualScrollingEnabled, VirtualScrollingMode): Pager and virtual scrolling
- Summary (
TotalSummary, GroupSummary, DxGridSummaryItem): Total and group aggregate summaries — Sum, Min, Max, Avg, Count — displayed in the grid footer
- Focused Row (
FocusedRowEnabled): Highlights a single row on click; exposes FocusedRowIndex and FocusedDataItem for programmatic access
- Toolbar (
ToolbarTemplate): Embed a toolbar at the top of the Grid with custom action buttons and data shaping controls
- Master-Detail (
DetailRowTemplate, ExpandDetailRow, CollapseDetailRow): Expandable detail rows with nested grids or arbitrary content; the detail template receives the master row's data item via context.DataItem
- Drag-and-Drop (
AllowDragRows, AllowedDropTarget, ItemsDropped): Row reordering within the same grid or moving rows between grids; requires ObservableCollection<T> for automatic UI refresh
Core Entry Point (Razor)
@rendermode InteractiveServer
<DxGrid Data="@Items" KeyFieldName="Id">
<Columns>
<DxGridCommandColumn />
<DxGridDataColumn FieldName="Name" />
<DxGridDataColumn FieldName="Date" DisplayFormat="d" />
</Columns>
</DxGrid>
Documentation & Navigation Guide
Getting Started
📄 references/getting-started.md
When you need to:
- Set up the Grid from scratch in a new or existing Blazor project
- Create your first grid with columns and data binding
- Enable interactive render mode for the grid page
Data Binding
📄 references/data-binding.md
When you need to:
- Bind to an in-memory list,
IQueryable, EF Core DbSet
- Use
EntityInstantFeedbackSource or EntityServerModeSource for large datasets
- Configure a
GridCustomDataSource for Web API / OData backends
- Understand which features are available per data-binding mode
Columns & Templates
📄 references/columns-and-templates.md
When you need to:
- Add, configure, or hide columns (
FieldName, Caption, Width, Visible)
- Customize cell display or edit templates (
CellDisplayTemplate, CellEditTemplate)
- Add a command column (New / Edit / Delete buttons)
- Create unbound columns with
UnboundExpression
- Use band (header) columns to group related columns
Editing & Validation
📄 references/editing-and-validation.md
When you need to:
- Enable row editing in EditRow, EditForm, PopupEditForm, or EditCell mode
- Handle
EditModelSaving and DataItemDeleting events
- Customize the edit form using
EditFormTemplate
- Validate user input with data annotations
Data Shaping
📄 references/data-shaping.md
When you need to:
- Sort by one or multiple columns programmatically or in the UI
- Group rows and configure group summaries
- Add filter row, filter panel, search box, or column filter menu
- Show the filter panel or customize filter-builder operators for a specific field
- Create total and group summary items
Export
📄 references/export.md
When you need to:
- Export grid data to CSV, XLS/XLSX, or PDF
- Customize exported cell styles, fonts, or document headers/footers
- Export only selected rows
Selection
📄 references/selection.md
When you need to:
- Enable single or multiple row selection
- Get/set
SelectedDataItem or SelectedDataItems
- Add a
DxGridSelectionColumn with checkboxes
- Select rows programmatically using
SelectRow, SelectDataItem
Drag-and-Drop
📄 references/drag-and-drop.md
When you need to:
- Enable row reordering within one grid (
AllowDragRows + AllowedDropTarget.Internal)
- Move rows between two grids (
AllowedDropTarget.External on source, All on target)
- Handle
ItemsDropped to update ObservableCollection<T> data sources
- Use
GetTargetDataSourceIndexAsync() for simplified insertion-index calculation
- Customize the drag hint with
DragHintTextTemplate
Examples
💻 examples/quickstart.razor — In-memory CRUD with EditRow, grouping, search box, summaries, and export
💻 examples/ef-core-crud.razor — Full EF Core CRUD with IDbContextFactory, async save/delete, and data reload
💻 examples/filter-panel-custom-date-operators.razor — FilterPanelDisplayMode with a custom Filter Builder that removes month operators for DueDate
💻 examples/custom-templates.razor — CellDisplayTemplate (badge rendering), EditFormTemplate with DxFormLayout, HeaderCaptionTemplate
💻 examples/drag-and-drop.razor — Row reordering within one grid and moving rows between two grids using ObservableCollection<T>
Quick Start Example
@page "/grid-demo"
@rendermode InteractiveServer
@inject WeatherForecastService ForecastService
<DxGrid @ref="Grid"
Data="@Forecasts"
KeyFieldName="Id"
EditMode="GridEditMode.EditRow"
EditModelSaving="OnEditModelSaving"
DataItemDeleting="OnDataItemDeleting"
ShowGroupPanel="true"
ShowSearchBox="true"
PageSize="10">
<Columns>
<DxGridCommandColumn />
<DxGridDataColumn FieldName="Date" DisplayFormat="d" SortOrder="GridColumnSortOrder.Ascending" SortIndex="0" />
<DxGridDataColumn FieldName="TemperatureC" Caption="Temp (°C)" />
<DxGridDataColumn FieldName="Forecast" />
<DxGridDataColumn FieldName="CloudCover" />
</Columns>
<TotalSummary>
<DxGridSummaryItem SummaryType="GridSummaryItemType.Count" FieldName="Date" />
</TotalSummary>
</DxGrid>
@code {
IGrid Grid { get; set; }
List<WeatherForecast> Forecasts { get; set; }
protected override void OnInitialized() {
Forecasts = ForecastService.GetForecast();
}
void OnEditModelSaving(GridEditModelSavingEventArgs e) {
var model = (WeatherForecast)e.EditModel;
if (e.IsNew)
Forecasts.Add(model);
else
e.CopyChangesToDataItem();
Grid.Reload();
}
void OnDataItemDeleting(GridDataItemDeletingEventArgs e) {
Forecasts.Remove((WeatherForecast)e.DataItem);
Grid.Reload();
}
}
What This Does
Displays a weather forecast list with inline row editing, a delete button, sorting by date, a group panel, a search box, and a total count summary. Clicking the pencil icon opens editors inline; clicking delete prompts for removal.
Key Properties & API Surface
DxGrid
| Property / Method | Type | Description |
|---|
Data | object | Binds the grid to any supported data source |
KeyFieldName | string | Primary key field for editing and selection |
EditMode | GridEditMode | EditRow, EditForm, PopupEditForm, EditCell |
SelectionMode | GridSelectionMode | Single or Multiple |
SelectedDataItems | IReadOnlyList<object> | Currently selected data items (two-way bindable) |
PageSize | int | Rows per page (default 20) |
VirtualScrollingEnabled | bool | Set to true to enable virtual scrolling; false by default |
VirtualScrollingMode | GridVirtualScrollingMode | Rows (default — row virtualization only), Columns (column virtualization only), RowsAndColumns (both); ignored when VirtualScrollingEnabled is false |
ShowGroupPanel | bool | Show/hide the group panel |
ShowSearchBox | bool | Show/hide the search box |
AllowSort | bool | Enable/disable sorting globally |
ExportToCsvAsync() | Task | Export data to CSV |
ExportToXlsxAsync() | Task | Export data to XLS/XLSX |
ExportToPdfAsync() | Task | Export data to PDF |
Reload() | void | Refresh grid data — do not await |
BeginUpdate() / EndUpdate() | void | Batch parameter changes |
DetailRowTemplate | RenderFragment<GridDetailRowTemplateContext> | Template for the expandable detail row; context.DataItem is the master row's data item |
DetailRowDisplayMode | GridDetailRowDisplayMode | Auto (default — expandable detail rows; users expand/collapse), Never (detail rows hidden), Always (detail rows always shown as preview strips; cannot be collapsed) |
AutoCollapseDetailRow | bool | Collapse the previously expanded detail row when another is expanded |
ExpandDetailRow(int) | void | Expand the detail row at the specified visible row index |
CollapseDetailRow(int) | void | Collapse the detail row at the specified visible row index |
CollapseAllDetailRows() | void | Collapse all expanded detail rows |
IsDetailRowExpanded(int) | bool | Returns true if the detail row at the specified index is expanded |
AllowDragRows | bool | Allows users to start drag-and-drop row operations |
AllowedDropTarget | GridAllowedDropTarget | Controls where rows dragged FROM this grid can land. None — cannot reorder or drop onto other components; Internal (default) — rows can be reordered within this grid only; External — rows can be dropped onto other components (not reordered internally); All — rows can be reordered within this grid AND dropped onto other components |
ItemsDropped | EventCallback<GridItemsDroppedEventArgs> | Fires when rows are dropped onto this grid; update the data source here |
DropTargetMode | GridDropTargetMode | BetweenRows (default) — drop between rows; Component — drop onto the grid as a whole |
DragHintTextTemplate | RenderFragment<GridDragHintTextTemplateContext> | Custom drag hint displayed while dragging |
DxGridDataColumn
| Property | Type | Description |
|---|
FieldName | string | Data source field to bind the column to |
Caption | string | Column header text |
Width | string | Column width (e.g., "150px", "20%") |
DisplayFormat | string | Format string for display values |
SortOrder | GridColumnSortOrder | Ascending or Descending |
SortIndex | int | Order of this column in multi-column sort |
AllowSort | bool | Allow user sorting for this column |
AllowGroup | bool | Allow grouping by this column |
AllowFilter | bool | Allow column filter menu |
UnboundExpression | string | Expression for calculated unbound columns |
GroupInterval | GridColumnGroupInterval | Date/number interval for grouped values |
GridEditModelSavingEventArgs
| Member | Type | Description |
|---|
EditModel | object | The edit model (a copy of the data item) — cast to your type |
DataItem | object | The original data item (null when IsNew is true) |
IsNew | bool | true when a new row is being created |
CopyChangesToDataItem() | void | Copies edit model changes to the original data item |
Reload | bool | Set to true to reload grid data after the handler completes — use instead of Grid.Reload() when no @ref is held |
GridDataItemDeletingEventArgs
| Member | Type | Description |
|---|
DataItem | object | The data item to delete — cast to your type |
Reload | bool | Set to true to reload grid data after the handler completes — use instead of Grid.Reload() when no @ref is held |
GridDetailRowTemplateContext
| Member | Type | Description |
|---|
DataItem | object | The master row's data item — cast to your model type to pass as a parameter to the detail component |
GridItemsDroppedEventArgs
| Member | Type | Description |
|---|
DroppedItems | IReadOnlyList<object> | The data items that were dragged — cast each to your model type |
TargetItem | object | The row near which the drop occurred; null if dropped at the end of the list |
TargetItemVisibleIndex | int | The visible row index of TargetItem |
DropPosition | GridItemDropPosition | Before or After relative to TargetItem |
Grid | IGrid | The target grid that received the drop |
SourceComponent | object | The component that the rows originated from; cast to IGrid for grid-to-grid scenarios |
GetTargetDataSourceIndexAsync() | Task<int> | Returns the zero-based index in the data source where the dropped items should be inserted |
Common Patterns
Pattern 1: Editing with EF Core
<DxGrid Data="@Employees"
KeyFieldName="EmployeeId"
EditMode="GridEditMode.EditForm"
CustomizeEditModel="OnCustomizeEditModel"
EditModelSaving="OnEditModelSaving"
DataItemDeleting="OnDataItemDeleting">
<Columns>
<DxGridCommandColumn />
<DxGridDataColumn FieldName="FirstName" />
<DxGridDataColumn FieldName="LastName" />
<DxGridDataColumn FieldName="HireDate" />
</Columns>
<EditFormTemplate Context="editFormContext">
<DxFormLayout>
<DxFormLayoutItem Caption="First Name:">
@editFormContext.GetEditor("FirstName")
</DxFormLayoutItem>
<DxFormLayoutItem Caption="Last Name:">
@editFormContext.GetEditor("LastName")
</DxFormLayoutItem>
</DxFormLayout>
</EditFormTemplate>
</DxGrid>
@code {
IEnumerable<Employee> Employees { get; set; }
NorthwindContext Northwind { get; set; }
protected override async Task OnInitializedAsync() {
Northwind = NorthwindContextFactory.CreateDbContext();
Employees = await Northwind.Employees.ToListAsync();
}
void OnCustomizeEditModel(GridCustomizeEditModelEventArgs e) {
if (e.IsNew)
((Employee)e.EditModel).EmployeeId = Employees.Max(x => x.EmployeeId) + 1;
}
async Task OnEditModelSaving(GridEditModelSavingEventArgs e) {
var model = (Employee)e.EditModel;
if (e.IsNew)
await Northwind.AddAsync(model);
else
e.CopyChangesToDataItem();
await Northwind.SaveChangesAsync();
Employees = await Northwind.Employees.ToListAsync();
}
async Task OnDataItemDeleting(GridDataItemDeletingEventArgs e) {
Northwind.Remove(e.DataItem);
await Northwind.SaveChangesAsync();
Employees = await Northwind.Employees.ToListAsync();
}
}
Pattern 2: Export to PDF via Toolbar
<DxGrid @ref="Grid" Data="@Items">
<Columns>
<DxGridDataColumn FieldName="Name" />
<DxGridDataColumn FieldName="Amount" />
</Columns>
<ToolbarTemplate>
<DxToolbar>
<DxToolbarItem Text="Export to PDF" Click="ExportPdf" />
</DxToolbar>
</ToolbarTemplate>
</DxGrid>
@code {
IGrid Grid;
async Task ExportPdf() {
await Grid.ExportToPdfAsync("report.pdf");
}
}
Pattern 3: Virtual Scrolling with In-Memory Data
Virtual scrolling requires VirtualScrollingEnabled="true". Use VirtualScrollingMode to choose between row-only (Rows, default) or row+column (RowsAndColumns) virtualization. Define Grid height via CSS — DxGrid has no Height property.
<DxGrid Data="@Items"
KeyFieldName="Id"
VirtualScrollingEnabled="true"
VirtualScrollingMode="GridVirtualScrollingMode.Rows"
CssClass="my-grid">
<Columns>
<DxGridDataColumn FieldName="Name" />
<DxGridDataColumn FieldName="Value" />
</Columns>
</DxGrid>
<style>
.my-grid {
height: 500px;
}
</style>
Note: When virtual scrolling is active, PageSize has no effect — all rows appear on a single page with a scrollbar.
Pattern 4: Master-Detail with Nested Grid
Master-detail uses DetailRowTemplate with a separate child component. The child receives the master row's data item as a [Parameter]. Always define the detail as a separate component — do not inline a second DxGrid directly inside the template in the same file.
@* MasterPage.razor — the master grid *@
@rendermode InteractiveServer
<DxGrid @ref="MasterGrid"
Data="@Customers"
KeyFieldName="Id"
AutoCollapseDetailRow="true">
<Columns>
<DxGridDataColumn FieldName="CompanyName" />
<DxGridDataColumn FieldName="Country" />
</Columns>
<DetailRowTemplate>
<CustomerOrdersDetail Customer="(Customer)context.DataItem" />
</DetailRowTemplate>
</DxGrid>
@code {
IGrid MasterGrid { get; set; }
List<Customer> Customers { get; set; }
protected override void OnInitialized() {
Customers = CustomerService.GetCustomers();
}
}
@* CustomerOrdersDetail.razor — the detail component *@
@rendermode InteractiveServer
<DxGrid Data="@Orders" KeyFieldName="OrderId" PageSize="5">
<Columns>
<DxGridDataColumn FieldName="OrderId" />
<DxGridDataColumn FieldName="OrderDate" DisplayFormat="d" />
<DxGridDataColumn FieldName="Amount" DisplayFormat="c" />
</Columns>
</DxGrid>
@code {
[Parameter]
public Customer Customer { get; set; }
List<Order> Orders { get; set; }
protected override void OnInitialized() {
Orders = OrderService.GetOrdersForCustomer(Customer.Id);
}
}
Key rules: context.DataItem in DetailRowTemplate is the master row's object — cast it to pass as a parameter. Always define the nested grid in a separate .razor file; inlining it directly causes render mode and lifecycle issues.
Pattern 5: Drag-and-Drop Row Reordering (Same Grid)
Use AllowDragRows="true" and AllowedDropTarget="GridAllowedDropTarget.Internal". The data source must be an ObservableCollection<T> so the grid reflects insertions/removals automatically.
<DxGrid Data="@Items"
KeyFieldName="Id"
AllowDragRows="true"
AllowedDropTarget="GridAllowedDropTarget.Internal"
ItemsDropped="OnItemsDropped">
<Columns>
<DxGridDataColumn FieldName="Name" />
<DxGridDataColumn FieldName="Priority" />
</Columns>
</DxGrid>
@code {
ObservableCollection<MyItem> Items { get; set; }
protected override void OnInitialized() {
Items = new ObservableCollection<MyItem>(DataService.GetItems());
}
void OnItemsDropped(GridItemsDroppedEventArgs e) {
var dropped = (MyItem)e.DroppedItems[0];
Items.Remove(dropped);
var target = (MyItem)e.TargetItem;
var index = target != null
? Items.IndexOf(target) + (e.DropPosition == GridItemDropPosition.After ? 1 : 0)
: Items.Count;
Items.Insert(index, dropped);
}
}
Pattern 6: Drag-and-Drop Between Two Grids
The source grid sets AllowDragRows="true" + AllowedDropTarget="GridAllowedDropTarget.External" — this permits dragging rows out to other components but keeps internal reordering disabled. The target sets AllowedDropTarget="GridAllowedDropTarget.All" (allows its own rows to reorder AND be dragged to other components) and handles ItemsDropped. Use e.SourceComponent and e.Grid to identify which ObservableCollection<T> to update. When inserting multiple rows, use .Reverse() to preserve their original order.
@* Source grid: rows can be dragged to external targets *@
<DxGrid @ref="SourceGrid"
Data="@SourceItems"
KeyFieldName="Id"
AllowDragRows="true"
AllowedDropTarget="GridAllowedDropTarget.External">
<Columns>
<DxGridDataColumn FieldName="Name" />
</Columns>
</DxGrid>
@* Target grid: allows internal reorder AND accepts external drops *@
<DxGrid Data="@TargetItems"
KeyFieldName="Id"
AllowDragRows="true"
AllowedDropTarget="GridAllowedDropTarget.All"
ItemsDropped="OnTargetItemsDropped">
<Columns>
<DxGridDataColumn FieldName="Name" />
</Columns>
</DxGrid>
@code {
IGrid SourceGrid { get; set; }
ObservableCollection<MyItem> SourceItems { get; set; }
ObservableCollection<MyItem> TargetItems { get; set; }
protected override void OnInitialized() {
SourceItems = new ObservableCollection<MyItem>(DataService.GetSourceItems());
TargetItems = new ObservableCollection<MyItem>(DataService.GetTargetItems());
}
ObservableCollection<MyItem> GetCollection(object grid) =>
grid == SourceGrid ? SourceItems : TargetItems;
void OnTargetItemsDropped(GridItemsDroppedEventArgs e) {
var source = GetCollection(e.SourceComponent);
var destination = GetCollection(e.Grid);
// Remove from source collection
foreach (var item in e.DroppedItems)
source.Remove((MyItem)item);
// Insert into destination at drop position (Reverse preserves display order)
var target = (MyItem)e.TargetItem;
var index = target != null
? destination.IndexOf(target) + (e.DropPosition == GridItemDropPosition.After ? 1 : 0)
: destination.Count;
foreach (var item in e.DroppedItems.Reverse())
destination.Insert(index, (MyItem)item);
}
}
Critical rules:
- Both grids' data sources must be
ObservableCollection<T> — plain List<T> will not reflect changes without Reload().
- Only the receiving grid needs
ItemsDropped.
AllowedDropTarget is a source-side property — it controls where rows dragged FROM this grid can land, not what this grid accepts.- Do not use
AllowRowDragDrop, RowDrop, or OnRowDrop — these properties and events do not exist.
Pattern 7: Multiple Row Selection with Selection Column
<DxGrid Data="@Items"
KeyFieldName="Id"
SelectionMode="GridSelectionMode.Multiple"
@bind-SelectedDataItems="@SelectedItems">
<Columns>
<DxGridSelectionColumn Width="50px" AllowSelectAll="true" />
<DxGridDataColumn FieldName="Name" />
</Columns>
</DxGrid>
@code {
IReadOnlyList<object> SelectedItems { get; set; } = new List<object>();
}
Troubleshooting
| Symptom | Cause | Fix |
|---|
| Grid renders but sorting/paging/editing doesn't work | Static render mode | Add @rendermode InteractiveServer (or WASM/Auto) to the page or component |
System.InvalidCastException when editing | Edit model type mismatch | Ensure the cast in EditModelSaving matches the data item type |
| A property named XXX is not found | FieldName doesn't match data model property name (case-sensitive) | Check the exact property name in your data class |
Grid is empty after Reload() | Data property not updated before reload | Re-assign the data collection, then call Reload() |
| Sorting/grouping breaks with server-mode | Unsupported feature with EntityServerModeSource | Use EntityInstantFeedbackSource or check the feature support table in references/data-binding.md |
Cannot pass the parameter 'X' to component 'DxGrid' with rendermode | Render mode isolation boundary issue | Move the Grid to a child component with its own @rendermode directive |
"Unhandled exception on the current circuit" with no detail | CircuitOptions.DetailedErrors not set | Add builder.Services.Configure<CircuitOptions>(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 <base href="/subpath/" /> 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 |
"Enumeration type XXX not registered for parse operation" | Custom enum used in Grid filter criteria | Call EnumProcessingHelper.RegisterEnum<MyEnum>() in Program.cs before builder.Build() |
InvalidCastException: ReadonlyThreadSafeProxyForObjectFromAnotherThread on edit | Accessing data item from an instant feedback source directly | Use e.GetDataItemValue<T>(nameof(MyItem.Field)) instead of casting e.DataItem directly |
| Virtual scrolling not working / rows not virtualized | VirtualScrollingEnabled not set | Set VirtualScrollingEnabled="true" on DxGrid; VirtualScrollingMode alone does nothing |
Compiler error: DxGrid has no Height attribute | Height is not a DxGrid property | Set Grid height via CSS: add CssClass="my-grid" and define .my-grid { height: 500px; } in a scoped or global stylesheet |
Constraints & Rules
Follow these rules in every interaction:
- 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 DxGrid API. Do not warn that a feature "may have been introduced in a recent version" as a way to justify inventing it.
- Filter panel API: Use
FilterPanelDisplayMode, not ShowFilterPanel. Set it to Always or Auto depending on whether the panel should always be visible.
- Filter builder operators: To change date operators such as
IsJanuary for a specific field, customize DxFilterBuilder inside FilterBuilderTemplate. DxGrid.CustomizeFilterMenu only affects the column filter menu and DxGridDataColumn.CustomizeFilterMenu does not exist.
- Build verification: After making changes, run
dotnet build before reporting success.
- NuGet packages: Use
DevExpress.Blazor only. Do not mix DevExpress package versions in one project.
- Render mode is mandatory:
DxGrid requires an interactive render mode for all interactive features (sorting, filtering, editing, paging). Always include @rendermode InteractiveServer (or equivalent) on the page or in a parent component.
- Namespace imports: Always include
@using DevExpress.Blazor in _Imports.razor or the Razor file.
- KeyFieldName for editing/selection: Always specify
KeyFieldName when enabling editing or selection. Without it, the Grid cannot track data item identity reliably.
- No destructive changes: Preserve existing code outside the Grid component. Only add or modify what is necessary.
- Version consistency: All
DevExpress.* NuGet packages must use the same version.
- License: A valid DevExpress license is required. If the user reports license errors, direct them to https://go.devexpress.com/Licensing_Documentation.aspx.
Using DevExpress Documentation MCP
If the DevExpress Docs MCP server is available (look for devexpress_docs_search and devexpress_docs_get_content tools):
- Search documentation:
devexpress_docs_search(technology="Blazor", query="your question")
- Fetch an article:
devexpress_docs_get_content(url="https://docs.devexpress.com/Blazor/...")
When to use MCP vs. built-in references:
- Built-in references: getting started, common editing patterns, key properties, and troubleshooting covered above.
- Use MCP for: version-specific API changes, advanced scenarios (context menus, custom data sources), exact method signatures you're unsure about.
- Always prefer MCP for: confirming exact event argument types, enum values, or complex server-mode configurations.
