syncfusion-javascript-dropdowntree

# Implementing Syncfusion Dropdown Tree --- ## When to Use This Skill Use the Dropdown Tree control when you need to: - **Display hierarchical data** in a compact dropdown format with tree-like structure - **Enable multiple selections** from tree items with checkbox support - **Load large datasets on-demand** (lazy loading) to optimize performance - **Customize tree appearance** with item templates, headers, and footers - **Handle parent-child dependencies** with automatic checkbox propagation - **Support multiple languages** with localization features - **Provide keyboard navigation** and accessibility for users with assistive technologies The Dropdown Tree is ideal for scenarios like organizational hierarchies, category selections, location/region pickers, and permission/role management interfaces. --- ## Component Overview The **Syncfusion Dropdown Tree** control allows you to select single or multiple values from hierarchical data displayed in a tree structure. Key features include: - **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](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](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](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](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](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) ```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 ```html <input type="text" id="ddtElement" /> ``` --- ## Core Concepts ### 1. Hierarchical Data Structure Hierarchical data uses nested arrays to represent parent-child relationships: ```typescript 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: ```typescript 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 | Property | Type | Description | Example | |----------|------|-------------|---------| | `dataSource` | DataManager \| Object[] | Array of data or DataManager instance | `[{...}, {...}]` | | `value` | string | Field name for item value/ID | `'id'` or `'code'` | | `text` | string | Field name for display text | `'name'` or `'title'` | | `child` | string \| FieldsModel | Field name for child collection (hierarchical) | `'children'` or `'items'` | | `parentValue` | string | Field name for parent reference (self-referential) | `'parentId'` or `'pid'` | | `hasChildren` | string | Field name indicating if item has children | `'hasChild'` or `'hasItems'` | | `expanded` | string | Field name for expanded state | `'expanded'` or `'isExpanded'` | | `selected` | string | Field name for selected state | `'selected'` or `'isSelected'` | | `iconCss` | string | Field name for icon CSS class | `'iconClass'` | | `imageUrl` | string | Field name for image URL | `'imageUrl'` or `'icon'` | | `htmlAttributes` | string | Field name for HTML attributes | `'htmlAttrs'` | | `tooltip` | string | Field name for tooltip text | `'title'` or `'tooltip'` | | `selectable` | string | Field name for item selectability | `'canSelect'` | | `query` | Query | External query for DataManager | Custom Query object | | `tableName` | string | Table name for server-side data | `'EmployeeTable'` | ### FieldsModel Examples #### Hierarchical Data with Custom Fields ```typescript let ddtree = new DropDownTree({ fields: { dataSource: hierarchicalData, value: 'id', text: 'name', child: 'subitems', expanded: 'isExpanded', iconCss: 'iconClass' } }); ddtree.appendTo('#ddtElement'); ``` #### Self-Referential Data ```typescript let ddtree = new DropDownTree({ fields: { dataSource: selfRefData, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' } }); ddtree.appendTo('#ddtElement'); ``` #### Remote Data with OData ```typescript 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 | Property | Type | Description | Default | |----------|------|-------------|---------| | `loadOnDemand` | boolean | Enable lazy loading of child items | `false` | | `autoCheck` | boolean | Enable parent-child checkbox dependency | `false` | | `checkDisabledChildren` | boolean | Include disabled children in parent check | `false` | | `expandOn` | ExpandOn | Trigger for expand/collapse action | `ExpandOn.Auto` | ### ExpandOn Enum Values | Value | Description | |-------|-------------| | `Auto` | Double-click on desktop, single-tap on mobile | | `Click` | Single-click/tap on both desktop and mobile | | `DblClick` | Double-click/tap on both desktop and mobile | | `None` | Expand/collapse disabled | ### TreeSettingsModel Examples #### Lazy Loading Configuration ```typescript 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 ```typescript 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 ```typescript 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**](references/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**](references/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**](references/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 ```typescript 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