Implementing Syncfusion Dropdown Tree

• Data Binding: Local (hierarchical/self-referential) and remote (OData, Web API, DataManager)
• Checkboxes: Multi-select with optional parent-child auto-check behavior
• Select All: Built-in checkbox in header to select/deselect all items
• Templates: Customize items, values, headers, footers, and no-records content
• Lazy Loading: Load child data on-demand to reduce initial bandwidth
• Sorting: Display items in ascending/descending order
• Filtering: Search and filter tree items dynamically
• Localization: Multi-language support with text customization
• Accessibility: Keyboard navigation and screen reader support
• Multi-Selection Modes: Box, Delimiter, Default, or Custom display modes

Documentation Navigation

Getting Started

📄 Read: references/getting-started.md

• Installation and package dependencies
• Development environment setup
• CSS imports and theme configuration
• Basic HTML initialization
• Creating your first Dropdown Tree with TypeScript and ES5 examples

Data Binding and Tree Structure

📄 Read: references/data-binding.md

• Local data binding with hierarchical structure
• Self-referential data binding patterns
• Remote data binding (OData, Web API, DataManager)
• Load on demand (lazy loading) configuration
• Field mapping and data structure requirements
• Practical examples with different data sources

Checkbox Features and Selection

📄 Read: references/checkbox-features.md

• Enable checkboxes with showCheckBox property
• Single item selection
• Auto-check propagation for parent-child items
• Select All functionality in the popup header
• Customizing Select All text and behavior
• Managing selected items programmatically

Templates and Customization

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

• Item template for custom list rendering
• Value template for selected value display
• Header template for popup header customization
• Footer template for popup footer content
• No Records template for empty state handling
• Action Failure template for error scenarios
• Template expression syntax and best practices

Localization and Accessibility

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

• Localization library setup and usage
• Multi-language text customization
• Default and custom locale configurations
• Keyboard navigation support
• Screen reader compatibility
• WCAG accessibility features

Quick Start Example

Basic Setup (TypeScript)

import { DropDownTree } from '@syncfusion/ej2-dropdowns';

// Define hierarchical data
let continents = [
    {
        code: 'AF', 
        name: 'Africa', 
        countries: [
            { code: 'NGA', name: 'Nigeria' },
            { code: 'EGY', name: 'Egypt' }
        ]
    },
    {
        code: 'AS', 
        name: 'Asia',
        expanded: true,
        countries: [
            { code: 'IND', name: 'India', selected: true },
            { code: 'JPN', name: 'Japan' }
        ]
    }
];

// Initialize Dropdown Tree
let ddtree = new DropDownTree({
    fields: { 
        dataSource: continents, 
        value: 'code', 
        text: 'name', 
        child: 'countries' 
    }
});

ddtree.appendTo('#ddtElement');

HTML Element

<input type="text" id="ddtElement" />

Core Concepts

1. Hierarchical Data Structure

Hierarchical data uses nested arrays to represent parent-child relationships:

let hierarchicalData = [
    {
        id: 1,
        name: 'Parent Item',
        children: [
            { id: 2, name: 'Child 1' },
            { id: 3, name: 'Child 2' }
        ]
    }
];

2. Self-Referential Data Structure

Self-referential data uses parent ID references:

let selfRefData = [
    { id: 1, name: 'Parent', parentId: null },
    { id: 2, name: 'Child 1', parentId: 1 },
    { id: 3, name: 'Child 2', parentId: 1 }
];

3. Single vs. Multiple Selection

• Single Selection: Users can select one item (default behavior)
• Multiple Selection: Enable with allowMultiSelection: true or showCheckBox: true

4. Parent-Child Checkbox Dependency

When autoCheck: true in treeSettings:

• Checking a parent auto-checks all children
• Unchecking a parent auto-unchecks all children
• Mixed states (intermediate) occur when only some children are checked

FieldsModel Configuration

The fields property uses FieldsModel to map data source fields to Dropdown Tree properties.

FieldsModel Properties

FieldsModel Examples

Hierarchical Data with Custom Fields

let ddtree = new DropDownTree({
    fields: {
        dataSource: hierarchicalData,
        value: 'id',
        text: 'name',
        child: 'subitems',
        expanded: 'isExpanded',
        iconCss: 'iconClass'
    }
});
ddtree.appendTo('#ddtElement');

Self-Referential Data

let ddtree = new DropDownTree({
    fields: {
        dataSource: selfRefData,
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChild'
    }
});
ddtree.appendTo('#ddtElement');

Remote Data with OData

import { DataManager, ODataV4Adaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Employees',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'EmployeeID',
        text: 'FirstName',
        hasChildren: 'EmployeeID'
    }
});
ddtree.appendTo('#ddtElement');

TreeSettingsModel Configuration

The treeSettings property uses TreeSettingsModel to configure tree-specific behavior.

TreeSettingsModel Properties

ExpandOn Enum Values

TreeSettingsModel Examples

Lazy Loading Configuration

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        loadOnDemand: true  // Children load when parent expands
    }
});
ddtree.appendTo('#ddtElement');

Auto-Check with Disabled Children Support

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    treeSettings: {
        autoCheck: true,
        checkDisabledChildren: true  // Disabled items get checked too
    }
});
ddtree.appendTo('#ddtElement');

Custom Expand Trigger

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        expandOn: 'Click'  // Single-click to expand/collapse
    }
});
ddtree.appendTo('#ddtElement');

📋 API Properties Reference

📄 Complete API properties documentation with examples and type specifications

🔗 Open api-properties.md

What's Inside:

• ✅ 55+ Properties - Every property documented with type, default value, and description
• ✅ 10 Categories - Essential, Selection, Templates, Popup, Filtering, Sorting, Styling, State, HTML Security, Localization
• ✅ 100+ Examples - Real-world code samples for each property
• ✅ Type Specifications - Complete type info and default values
• ✅ Best Practices - Usage patterns and recommendations

🔧 API Methods Reference

📄 Complete API methods documentation with parameter details and examples

🔗 Open api-methods.md

What's Inside:

• ✅ 16 Methods - All component methods fully documented
• ✅ 6 Categories - Lifecycle, Data & Value, Popup, DOM, Event Management, Module Injection
• ✅ Parameter Specs - Complete parameter types, descriptions, and return types
• ✅ Working Examples - Production-ready code for each method
• ✅ Use Cases - When and how to use each method

🎯 API Events Reference

📄 Complete API events documentation with event argument properties and examples

🔗 Open api-events.md

What's Inside:

• ✅ 13 Events - All component events fully documented
• ✅ 7 Categories - Selection, Data, Filtering, Popup, Focus, Keyboard, Lifecycle
• ✅ 8 Event Argument Types - Complete property mappings (30+ properties)
• ✅ Event Details - When each event triggers and what data it provides
• ✅ Real Examples - Practical event handling implementations

Common Patterns

Pattern 1: Multiple Selection with Checkboxes

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    treeSettings: { autoCheck: true },
    change: (args) => {
        console.log('Selected items:', args.value);
    }
});
ddtree.appendTo('#ddtElement');

Use when: User needs to select multiple items with parent-child dependency.

Pattern 2: Load Large Datasets On-Demand

let ddtree = new DropDownTree({
    fields: { 
        dataSource: dataManager, 
        value: 'id', 
        text: 'name',
        parentValue: 'parentId'
    },
    treeSettings: { loadOnDemand: true }
});
ddtree.appendTo('#ddtElement');

Use when: Working with large hierarchies (1000+ items).

Pattern 3: Custom Item Display with Templates

let ddtree = new DropDownTree({
    fields: { dataSource: data, text: 'name', value: 'id' },
    itemTemplate: '<div class="item-row"><span>${name}</span> <small>${department}</small></div>',
    valueTemplate: '<span class="selected-badge">${name}</span>'
});
ddtree.appendTo('#ddtElement');

Use when: Need to display additional data fields.

Pattern 4: Remote Data with Filtering

import { DataManager, ODataV4Adaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://api.example.com/items',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'id',
        text: 'name'
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search items...',
    filterType: 'Contains'
});
ddtree.appendTo('#ddtElement');

Use when: Fetching data from remote service with search capability.

Pattern 5: Customized Select All with Delimiter Mode

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Select All Items',
    unSelectAllText: 'Clear All',
    mode: 'Delimiter',
    delimiterChar: '; ',
    allowMultiSelection: true
});
ddtree.appendTo('#ddtElement');

Use when: Want friendly checkbox text and delimited display.

Pattern 6: Dynamic Data Update

let ddtree = new DropDownTree({
    fields: { dataSource: [], value: 'id', text: 'name', child: 'items' }
});
ddtree.appendTo('#ddtElement');

// Later, update data
let newData = [{ id: 1, name: 'Item 1', items: [] }];
ddtree.fields.dataSource = newData;
ddtree.refresh();  // Re-render

Use when: Data changes dynamically after initialization.

Pattern 7: Programmatic Value Setting with Validation

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', child: 'items' },
    showCheckBox: true,
    change: (args) => {
        if (args.value.length > 5) {
            console.warn('Maximum 5 items can be selected');
            // Reset to previous value
            ddtree.value = args.oldValue;
        }
    }
});
ddtree.appendTo('#ddtElement');

Use when: Need to enforce selection constraints.

Use Cases & Implementation Guide

Organizational Hierarchy Navigation

Scenario: Department/Employee selection with multi-select and role assignment

let employees = [
    { id: 1, name: 'IT Department', hasChild: true },
    { id: 2, pid: 1, name: 'John Doe', department: 'IT' },
    { id: 3, pid: 1, name: 'Jane Smith', department: 'IT' },
    { id: 4, name: 'HR Department', hasChild: true },
    { id: 5, pid: 4, name: 'Mike Johnson', department: 'HR' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: employees, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    treeSettings: { autoCheck: true },
    itemTemplate: '<div>${name} <span class="text-muted">${department}</span></div>',
    change: (args) => {
        assignRolesToSelectedEmployees(args.value);
    }
});
ddtree.appendTo('#employeeSelection');

Geographic Location/Region Selection

Scenario: Country → State → City selection with lazy loading

import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'api/locations',
            adaptor: new WebApiAdaptor()
        }),
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChildren'
    },
    treeSettings: { 
        loadOnDemand: true  // Load children on demand
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search locations...',
    change: (args) => {
        updateMapWithSelectedLocation(args.value);
    }
});
ddtree.appendTo('#locationPicker');

Category-Based Product Filtering

Scenario: Display product categories with item counts and icons

let categories = [
    { 
        id: 'cat1', 
        name: 'Electronics', 
        count: 125,
        icon: 'e-icons e-mobile',
        products: [
            { id: 'prod1', name: 'Mobile Phones', count: 45, icon: 'e-icons e-phone' },
            { id: 'prod2', name: 'Laptops', count: 30, icon: 'e-icons e-laptop' }
        ]
    }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: categories, 
        value: 'id', 
        text: 'name', 
        child: 'products',
        iconCss: 'icon'
    },
    itemTemplate: `
        <div class="category-item">
            <i class="\${icon}"></i>
            <span>\${name}</span>
            <span class="badge">\${count}</span>
        </div>
    `,
    change: (args) => {
        filterProductsByCategories(args.value);
    }
});
ddtree.appendTo('#categorySelector');

Permission/Role Management

Scenario: Multi-level permission hierarchy with selective enabling

let permissions = [
    { id: 'admin', name: 'Admin', hasChild: true },
    { id: 'admin-users', pid: 'admin', name: 'Manage Users' },
    { id: 'admin-system', pid: 'admin', name: 'System Settings' },
    { id: 'user', name: 'User', hasChild: true, disabled: true },
    { id: 'user-profile', pid: 'user', name: 'Edit Profile' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: permissions, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Grant All Permissions',
    unSelectAllText: 'Revoke All Permissions',
    treeSettings: { autoCheck: true },
    change: (args) => {
        savePermissionsToRole(args.value);
    }
});
ddtree.appendTo('#permissionSelector');

Next Steps

1. Start with references/getting-started.md to install dependencies and create your first control
2. Choose your data source and follow the appropriate pattern in references/data-binding.md
3. Enable checkboxes if multi-selection is needed (references/checkbox-features.md)
4. Customize appearance with templates as required (references/templates-and-customization.md)
5. Reference this API documentation as needed during implementation

For implementation assistance with specific features or advanced scenarios, reference the appropriate guide above.