devexpress/agent-skills/devexpress-blazor-treelist

DevExpress Blazor TreeList

DxTreeList is a hierarchical data grid for Blazor. It displays data as a tree with expandable/collapsible rows based on parent-child key relationships. It shares most of DxGrid's feature set — sorting, filtering, CRUD editing, export, selection — and adds tree-specific capabilities such as multi-level expand/collapse, load-on-demand child nodes, and tree filtering modes.

When to Use This Skill

• Display hierarchical data (organizational charts, product categories, file systems, bill of materials)
• Bind flat data with parent-child ID relationships (KeyFieldName + ParentKeyFieldName)
• Sort, filter, or page tree nodes
• Implement CRUD for hierarchical data (create, edit, delete nodes)
• Export tree data to CSV, XLS/XLSX, or PDF
• Load child nodes on demand from a remote API
• Select single or multiple tree nodes with checkboxes
• Reorder tree nodes within the TreeList or move rows between TreeLists and Grids with drag-and-drop
• Change node hierarchy (re-parent nodes) via drag-and-drop

Prerequisites & Installation

NuGet Package

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

Setup (existing project)

1. Register DevExpress resources 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 inside <head>:

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

Before generating code, ask:

1. Render mode: Are you using InteractiveServer, InteractiveWebAssembly, or InteractiveAuto? (TreeList requires an interactive render mode for tree expansion, filtering, and editing.)
2. Data structure: Is your data a flat list with parent ID references, or is it already a nested object graph?
3. Key fields: What are the primary key field and the parent key field names? What is the root value (the parent ID of root nodes — null, 0, or something else)?
4. Features needed: Do you need editing? Export? Selection? Load-on-demand children?
5. New or existing project?: Are you adding the TreeList to an existing project or starting fresh?

Component Overview

DxTreeList provides:

• Data Binding (Data, KeyFieldName, ParentKeyFieldName): Binds flat data with parent-child relationships; RootValue defines root nodes
• Column Types (DxTreeListDataColumn, DxTreeListCommandColumn, DxTreeListSelectionColumn, DxTreeListBandColumn): Same column model as DxGrid
• Tree Navigation (AllowExpandCollapse, ExpandedRowKeys): Expand/collapse tree levels, expand all, collapse all
• Data Shaping (AllowSort, ShowSearchBox, FilterPanelDisplayMode): Sort, filter row, filter panel, search box
• Editing (EditMode, EditModelSaving, DataItemDeleting): EditRow, EditForm, PopupEditForm, EditCell
• Selection (SelectionMode, SelectedDataItems): Single and multiple node selection
• Export (ExportToCsvAsync, ExportToXlsxAsync, ExportToPdfAsync): CSV, XLS/XLSX, PDF
• Load on Demand (ChildrenLoaded event): Load child nodes asynchronously when a node is expanded
• Summary (TotalSummary, DxTreeListSummaryItem): Total aggregate summaries — Sum, Min, Max, Avg, Count — displayed in the footer
• Focused Row (FocusedRowEnabled): Highlights a single row on click; use GetFocusedRowIndex(), GetFocusedDataItem(), and SetFocusedRowIndex() to work with the current row
• Toolbar (ToolbarTemplate): Embed a toolbar at the top of the TreeList with custom action buttons and data shaping controls
• Drag-and-Drop (AllowDragRows, AllowedDropTarget, ItemsDropped): Row reordering within the same TreeList, moving rows between TreeLists and Grids, and changing node hierarchy (re-parenting); requires ObservableCollection<T> for automatic UI refresh

Core Entry Point (Razor)

@rendermode InteractiveServer
 
<DxTreeList Data="@TreeData"
            KeyFieldName="Id"
            ParentKeyFieldName="ParentId">
    <Columns>
        <DxTreeListDataColumn FieldName="Name" Caption="Task" />
        <DxTreeListDataColumn FieldName="AssignedTo" />
        <DxTreeListDataColumn FieldName="DueDate" DisplayFormat="d" />
    </Columns>
</DxTreeList>

Documentation & Navigation Guide

Getting Started

📄 references/getting-started.md

When you need to:

• Set up the TreeList from scratch
• Create your first hierarchical data display
• Understand key field configuration

Data Binding

📄 references/data-binding.md

When you need to:

• Bind to flat data with KeyFieldName / ParentKeyFieldName
• Configure RootValue for non-null/non-zero root nodes
• Load child nodes on demand with the ChildrenLoaded event

Editing & Validation

📄 references/editing-and-validation.md

When you need to:

• Enable CRUD for tree nodes
• Add / edit / delete nodes with EditModelSaving and DataItemDeleting
• Customize the edit form
• Open the edit form from a toolbar or external button for the current focused or selected row

Data Shaping

📄 references/data-shaping.md

When you need to:

• Sort by columns, add filter row, search box
• Create total or group summaries
• Show the filter panel or customize filter-builder operators for a specific field

Export

📄 references/export.md

When you need to:

• Export tree data to CSV, XLSX, or PDF
• Control which rows are exported (expanded, all, selected)

Drag-and-Drop

📄 references/drag-and-drop.md

When you need to:

• Reorder rows within the TreeList
• Move rows between TreeLists or Grids
• Change node hierarchy (re-parent nodes) via drag-and-drop
• Handle the ItemsDropped event to update the data source

Examples

💻 examples/quickstart.razor — Hierarchical CRUD with CustomizeEditModel, search box, summaries, and export 💻 examples/edit-form-selected-item.razor — EditFormTemplate plus an external button that edits the current selected/focused row 💻 examples/filter-panel-custom-date-operators.razor — FilterPanelDisplayMode with a custom Filter Builder that removes month operators for DueDate 💻 examples/load-on-demand.razor — Async child loading via ChildrenLoaded for large trees

Quick Start Example

@page "/treelist-demo"
@rendermode InteractiveServer
 
<DxTreeList Data="@Tasks"
            KeyFieldName="Id"
            ParentKeyFieldName="ParentId"
            EditMode="TreeListEditMode.EditRow"
            EditModelSaving="OnEditModelSaving"
            DataItemDeleting="OnDataItemDeleting">
    <Columns>
        <DxTreeListCommandColumn />
        <DxTreeListDataColumn FieldName="Name" Caption="Task" />
        <DxTreeListDataColumn FieldName="AssignedTo" Caption="Assignee" />
        <DxTreeListDataColumn FieldName="StartDate" DisplayFormat="d" />
        <DxTreeListDataColumn FieldName="DueDate" DisplayFormat="d" />
        <DxTreeListDataColumn FieldName="Status" />
    </Columns>
</DxTreeList>
 
@code {
    List<TaskItem> Tasks { get; set; }
 
    protected override void OnInitialized() {
        Tasks = new List<TaskItem> {
            new TaskItem { Id = 1, ParentId = 0, Name = "Project Alpha", AssignedTo = "Alice", StartDate = DateTime.Today, DueDate = DateTime.Today.AddMonths(3), Status = "Active" },
            new TaskItem { Id = 2, ParentId = 1, Name = "Design Phase", AssignedTo = "Bob", StartDate = DateTime.Today, DueDate = DateTime.Today.AddDays(30), Status = "In Progress" },
            new TaskItem { Id = 3, ParentId = 1, Name = "Development Phase", AssignedTo = "Carol", StartDate = DateTime.Today.AddDays(31), DueDate = DateTime.Today.AddDays(90), Status = "Pending" },
            new TaskItem { Id = 4, ParentId = 3, Name = "Backend API", AssignedTo = "Dave", StartDate = DateTime.Today.AddDays(31), DueDate = DateTime.Today.AddDays(60), Status = "Pending" },
            new TaskItem { Id = 5, ParentId = 3, Name = "Frontend UI", AssignedTo = "Eve", StartDate = DateTime.Today.AddDays(61), DueDate = DateTime.Today.AddDays(90), Status = "Pending" },
        };
    }
 
    async Task OnEditModelSaving(TreeListEditModelSavingEventArgs e) {
        var model = (TaskItem)e.EditModel;
        if (e.IsNew) {
            model.Id = Tasks.Max(t => t.Id) + 1;
            Tasks.Add(model);
        } else {
            e.CopyChangesToDataItem();
        }
    }
 
    async Task OnDataItemDeleting(TreeListDataItemDeletingEventArgs e) {
        var item = (TaskItem)e.DataItem;
        // Remove the item and all its descendants
        RemoveWithDescendants(item.Id);
    }
 
    void RemoveWithDescendants(int id) {
        var children = Tasks.Where(t => t.ParentId == id).Select(t => t.Id).ToList();
        foreach (var childId in children)
            RemoveWithDescendants(childId);
        Tasks.RemoveAll(t => t.Id == id);
    }
 
    class TaskItem {
        public int Id { get; set; }
        public int ParentId { get; set; }
        public string Name { get; set; }
        public string AssignedTo { get; set; }
        public DateTime StartDate { get; set; }
        public DateTime DueDate { get; set; }
        public string Status { get; set; }
    }
}

Key Properties & API Surface

DxTreeList

DxTreeListDataColumn

Key Differences from DxGrid