syncfusion-aspnetcore-dropdown-tree

Implementing Syncfusion DropDownTree Component

The Syncfusion DropDownTree control is a dropdown component that displays hierarchical tree data structures, allowing users to select single or multiple values from a tree hierarchy. It combines the features of a traditional dropdown list with the hierarchical organization of a tree structure, making it ideal for applications requiring organized, nested data selection.

When to Use This Skill

Use this skill when you need to:

• Display hierarchical data in a dropdown format where items have parent-child relationships
• Enable tree-based selection with expand/collapse node functionality
• Support multi-selection with checkbox or keyboard navigation
• Implement custom templates for item display, headers, footers, and selected value representation
• Bind data from local JavaScript arrays, remote servers (OData, Web API), or lazy-load on demand
• Maintain accessibility with keyboard support (arrow keys, Enter, Space) and ARIA attributes
• Localize the component for different cultures and languages
• Prevent node selection for parent nodes while allowing child selection

Key Features Overview

The DropDownTree component provides comprehensive functionality for tree-based dropdown selection:

• Data Binding Options: Hierarchical data, self-referential data structures, remote data services with DataManager adaptors
• Selection Modes: Single selection, multi-selection with checkboxes, delimiter-separated display, chip/box mode, or custom templates
• Keyboard Navigation: Full keyboard support with arrow keys, Enter, Space, Home, End, Alt+Up/Down, Escape
• Custom Templates: Item templates, value templates, header templates, footer templates, no-records templates, action-failure templates
• Tree Configuration: Expand behavior (click, double-click, auto), load on demand (lazy loading), auto-check parent-child dependencies
• Accessibility: WAI-ARIA compliant with listbox roles, treeitem roles, ARIA attributes, screen reader support
• Filtering: Real-time search with configurable filter types (StartsWith, EndsWith, Contains), case sensitivity, accent handling
• Persistence: State retention across browser sessions
• RTL Support: Right-to-left rendering for Arabic, Hebrew, and other RTL languages

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Platform setup and prerequisites
• NuGet package installation
• Script and stylesheet references
• Tag helper configuration
• Basic DropDownTree initialization
• First rendering example with data binding
• Building blocks needed before advanced features

Data Binding and Hierarchy

📄 Read: references/data-binding.md

• Hierarchical data source binding with nested array structures
• Self-referential data structures with parent-value relationships
• Remote data binding with DataManager and adaptors (OData, ODataV4, WebAPI, URL)
• Load on demand (lazy loading) for large datasets
• Field mapping configuration (text, value, child, parentValue, hasChildren)
• Query support for remote data filtering
• Preventing node selection with the selectable property

Selection and Checkbox Features

📄 Read: references/checkbox-and-selection.md

• Enabling checkbox mode with showCheckBox property
• Multi-selection with allowMultiSelection property
• Auto-check dependency with parent-child synchronization
• Select All functionality in popup header
• Display modes (Default, Delimiter, Box, Custom) for selected items
• Custom template for selected item representation
• Check state management and prevention for disabled children
• Controlling expand behavior and tree interaction modes

Templates and Customization

📄 Read: references/templates-and-customization.md

• Item template for customizing list item appearance
• Value template for customizing selected value display
• Header template for popup header customization
• Footer template for popup footer customization
• No records template for empty search results
• Action failure template for remote data errors
• Custom template modes (Default, Delimiter, Box, Custom) for multi-selection display
• CSS class customization and HTML attribute mapping
• Styling and visual customization techniques

Properties and Configuration

📄 Read: references/properties-and-configuration.md

• Complete property reference including filtering, appearance, behavior, data settings
• Expand behavior configuration (Auto, Click, DblClick, None)
• Filter types and filter bar customization
• Float label types and placeholder text
• Persistence and state management
• RTL and locale settings
• Icon CSS and image URL mapping
• HTML attributes and CSS class application
• Destruction behavior when popup closes

Events and Interactions

📄 Read: references/events-and-interactions.md

• Change event and value tracking
• Selection events (select/unselect actions)
• Before open/popup events for preventing or customizing popup display
• Data bound event for remote data completion
• Filtering event for custom filter implementation
• Keyboard interaction event handling
• Focus and blur events for state management
• Event arguments and properties available in handlers

Accessibility and Globalization

📄 Read: references/accessibility-and-globalization.md

• Keyboard navigation shortcuts and interaction patterns
• ARIA attributes and WAI-ARIA compliance
• Screen reader support and accessible markup
• Focus management and keyboard event handling
• Localization and culture-specific text customization
• RTL (right-to-left) language support
• Multi-language string customization
• Accessibility best practices for dropdown trees

Quick Start Example

Basic Initialization

<!-- ASP.NET Core Razor Template -->
@{
    var treeData = new List<TreeNode>
    {
        new TreeNode { Id = "1", Text = "Item 1" },
        new TreeNode { Id = "2", Text = "Item 2", Children = new List<TreeNode>
        {
            new TreeNode { Id = "3", Text = "Child 1" },
            new TreeNode { Id = "4", Text = "Child 2" }
        }}
    };
}

<ejs-dropdowntree id="tree" placeholder="Select an item">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

With Checkbox Support

<ejs-dropdowntree id="treeCheckbox" showCheckBox="true">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

With Templates

@{
    var itemTemp = "<span>${Text} (${Id})</span>";
    var valueTemp = "<span>Selected: ${Text}</span>";
}

<ejs-dropdowntree id="treeTemplate" itemTemplate="@itemTemp" valueTemplate="@valueTemp">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Common Patterns

Pattern 1: Hierarchical Organization Categories

Scenario: Display product categories in a hierarchical structure

<ejs-dropdowntree id="categories" placeholder="Select Category">
    <e-dropdowntree-treeSettings expandOn="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@CategoryHierarchy" text="CategoryName" value="CategoryId" child="SubCategories"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 2: Multi-Select with Checkboxes

Scenario: Allow users to select multiple items with automatic parent-child dependency

<ejs-dropdowntree id="multiSelect" showCheckBox="true" allowMultiSelection="true" mode="Box">
    <e-dropdowntree-treeSettings autoCheck="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 3: Lazy Loading Large Datasets

Scenario: Load only visible nodes to improve performance with large trees

<ejs-dropdowntree id="lazyLoad">
    <e-dropdowntree-treeSettings loadOnDemand="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@RemoteDataManager" text="Name" value="Id" child="Children" hasChildren="HasChild"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 4: Remote Data with Filtering

Scenario: Fetch tree data remotely and enable real-time search C# (TreeViewController.cs):

public ActionResult RemoteData()
{
    DropDownTreeFields parentData = new DropDownTreeFields();
    DropDownTreeFields childData = new DropDownTreeFields();
    object data = new DataManager
    {
        Url = "https://services.odata.org/V4/Northwind/Northwind.svc",
        Adaptor = "ODataV4Adaptor",
        CrossDomain = true
    };
    // Parent data mapping
    parentData.Query = "new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)";
    parentData.Value = "EmployeeID";
    parentData.Text = "FirstName";
    parentData.HasChildren = "EmployeeID";
    parentData.Child = childData;
    parentData.DataSource = data;
    // Child data mapping  
    childData.Query = "new ej.data.Query().from('Orders').select('OrderID,EmployeeID,ShipName').take(5)";
    childData.Value = "OrderID";
    childData.Text = "ShipName";
    childData.ParentValue = "EmployeeID";
    childData.DataSource = data;
    ViewBag.remoteFields = parentData;
    return View();
}

<ejs-dropdowntree id="remoteFilter" allowFiltering="true" filterType="StartsWith">
    <e-dropdowntree-fields child="ViewBag.child" query="new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)" value="EmployeeID" text="FirstName" hasChildren="EmployeeID">
        <e-data-manager url="https://services.odata.org/V4/Northwind/Northwind.svc" adaptor="ODataV4Adaptor" crossDomain="true"></e-data-manager>
    </e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 5: Custom Display Modes

Scenario: Display selected multiple items in chip format

<ejs-dropdowntree id="chipMode" showCheckBox="true" allowMultiSelection="true" mode="Box" delimiterChar=",">
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Key Properties Reference

Property	Type	Default	Purpose
dataSource	DataManager | Array	-	Specifies the data items for the DropDownTree
fields	FieldsModel	-	Maps data source fields to DropDownTree properties
value	string[]	-	Gets/sets the currently selected value(s)
text	string	-	Gets the currently selected item text
showCheckBox	boolean	false	Enables checkbox mode for multiple selection
allowMultiSelection	boolean	false	Enables multi-selection without checkboxes
allowFiltering	boolean	false	Enables filter bar for searching items
enabled	boolean	true	Enables/disables the component
readonly	boolean	false	Sets read-only state
mode	Mode	'Default'	Display mode for selected items (Default, Delimiter, Box, Custom)
treeSettings	TreeSettings	-	Configures tree expansion and selection behavior
itemTemplate	string | Function	-	Template for customizing item display
valueTemplate	string | Function	-	Template for customizing selected value display
headerTemplate	string | Function	-	Template for popup header
footerTemplate	string | Function	-	Template for popup footer
noRecordsTemplate	string | Function	-	Template when no items found
actionFailureTemplate	string | Function	-	Template when remote data fails
customTemplate	string | Function	-	Custom template for selected items with mode='Custom'
placeholder	string	-	Watermark text for input element
floatLabelType	FloatLabelType	'Never'	Label floating behavior
locale	string	'en'	Culture for localization
enableRtl	boolean	false	Right-to-left rendering
enablePersistence	boolean	false	Persist state across sessions
cssClass	string	-	CSS class for styling
filterType	TreeFilterType	'StartsWith'	Search filter algorithm
ignoreCase	boolean	true	Case-insensitive search
ignoreAccent	boolean	false	Ignore diacritical marks in search

Common Use Cases

1. Organizational Hierarchies: Display employee reporting structures, department hierarchies
2. File System Navigation: Show folder structures with expandable directories
3. Category Selection: Product categories with subcategories for e-commerce
4. Geographic Hierarchies: Country-State-City nested selections
5. Permission/Role Hierarchies: Multi-level permission or role selection
6. Task Breakdown Structures: Project tasks organized hierarchically
7. Localization Selection: Language families and specific languages
8. Feature/Module Selection: Application features organized by module and feature

---

Next Steps: Choose a reference document above based on your current task. Each reference file contains detailed examples, property explanations, and implementation guidelines specific to that feature area.