Implementing Dropdown Tree

When to Use This Skill

• Display hierarchical data - Show nested categories, organizational structures, file trees, or department hierarchies
• Enable multi-selection - Allow users to select multiple items with checkbox support or keyboard modifiers
• Support lazy loading - Optimize performance with large datasets by loading children on demand
• Customize display - Use templates to format items, headers, footers, selected values, or error states
• Implement filtering - Enable search functionality with configurable filter types (StartsWith, EndsWith, Contains)
• Ensure accessibility - Provide WAI-ARIA compliance, keyboard navigation, and screen reader support
• Support multiple languages - Localize UI with customizable keys and RTL support
• Bind remote data - Integrate with OData, OData V4, Web APIs, or other remote data services
• Handle complex selection logic - Use events, auto-check hierarchy, or selective node disabling

Component Overview

• Hierarchical display: Local (hierarchical/self-referential) and remote data sources with flexible binding
• Multi-selection modes: Checkboxes with auto-check, multi-select with Ctrl/Shift keys, single select (default)
• Flexible templates: Item, value, header, footer, noRecords, and actionFailure templates for custom rendering
• Performance optimization: Lazy loading (load-on-demand) for efficient large dataset handling
• Search & filtering: Built-in filter bar with configurable filter types and case sensitivity options
• Comprehensive events: change, select, dataBound, filtering, beforeOpen, focus, keyPress, and popup events
• Accessibility: Full WAI-ARIA (roles, attributes), keyboard navigation, screen reader support, WCAG 2.2 compliance
• Localization: Multi-language support with 4 customizable keys and locale override
• RTL support: Right-to-left layout rendering
• Tree settings: Advanced configuration (expandOn, autoCheck, loadOnDemand, checkDisabledChildren)
• Field mapping: Flexible data structure support (value, text, child, parentValue, expanded, hasChildren, selectable, iconCss, imageUrl, htmlAttributes)
• Display modes: Default, Delimiter, and Custom modes for selected items

Documentation and Navigation Guide

Getting Started

• Installation and package dependencies (npm install command)
• React/TypeScript project setup (Vite and Create React App)
• Basic component implementation and initialization
• CSS imports and theme configuration
• First render and minimal working example

Data Binding

• Local data binding (hierarchical and self-referential structures)
• Remote data with DataManager and various adaptors (OData, OData V4, WebAPI, URL)
• Field mapping for value, text, child, parentValue, expanded, hasChildren
• Load on demand (lazy loading) for large datasets
• Preventing node selection with selectable field
• Query configuration for remote data services

Checkbox & Multi-Selection

• Enabling checkbox support with

  showCheckBox

  property
• Multi-selection workflow and accessing selected values
• Auto-check hierarchical behavior (parent-child synchronization)
• Select All feature with customizable

  selectAllText

  and

  unSelectAllText

• Intermediate checkbox states for partial selection
• CheckDisabledChildren behavior for disabled nodes

Templates

• Item template for custom list item rendering
• Value template for selected display customization
• Header template for static content above items
• Footer template for static content below items
• NoRecords template for empty state handling
• ActionFailure template for error state handling
• CustomTemplate for multi-select display customization
• Template expression syntax and data access patterns

Multi-Selection & Filtering

• allowMultiSelection

  property and Ctrl/Shift keyboard interaction
• Display modes: Default, Delimiter, Custom

• delimiterChar

  and

  mode

  configuration

• allowFiltering

  and filter bar implementation
• Filter types: StartsWith, EndsWith, Contains

• filterBarPlaceholder

  customization

• ignoreCase

  and

  ignoreAccent

  options

Tree Settings & Configuration

• loadOnDemand

  for lazy loading implementation

• autoCheck

  for hierarchical checkbox synchronization

• expandOn

  behavior (Auto, Click, DblClick, None)

• checkDisabledChildren

  for disabled node handling
• Tree expansion and collapse control

Field Mapping & Custom Data Structures

• Core fields: value, text, dataSource, child, parentValue
• Node state fields: expanded, hasChildren, selected, selectable
• Display enhancement fields: iconCss, imageUrl, htmlAttributes
• Query and tableName for remote data
• Nested field mapping for hierarchical data

Advanced Features & API Reference

• Properties (60+ properties with descriptions and examples)
• Methods (getSelectedNodes, getCheckedNodes, setCheckedNodes, etc.)
• Events (change, select, dataBound, filtering, beforeOpen, focus, keyPress, popup)
• Event arguments (EventArgs structures with property descriptions)
• Styling and CSS customization
• Performance optimization techniques

Accessibility & Localization

• WCAG 2.2 and Section 508 compliance standards
• WAI-ARIA attributes and roles (listbox, treeitem, checkbox, group, etc.)
• Keyboard navigation shortcuts (Alt+Down, Arrow keys, Enter, Space, etc.)
• Screen reader and assistive technology support
• Localization keys (noRecordsTemplate, actionFailureTemplate, overflowCountTemplate, totalCountTemplate)
• Culture customization with locale property
• RTL (Right-to-Left) language support with enableRtl

Quick Start

Basic Dropdown Tree with Hierarchical Data

import { DropDownTreeComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-dropdowns/styles/material.css';

function App() {
  const data = [
    { id: '1', name: 'Electronics', expanded: true },
    { id: '2', name: 'Laptops', parentId: '1' },
    { id: '3', name: 'Phones', parentId: '1' },
    { id: '4', name: 'Appliances' },
  ];

  return (
    <DropDownTreeComponent
      id="dropdowntree"
      fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
      placeholder="Select an item"
    />
  );
}

export default App;

With Checkboxes and Auto-Check

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
  showCheckBox={true}
  showSelectAll={true}
  treeSettings={{ autoCheck: true }}
  placeholder="Select items"
/>

With Filtering

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  allowFiltering={true}
  filterType="Contains"
  filterBarPlaceholder="Search items..."
  placeholder="Select an item"
/>

With Custom Templates

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  itemTemplate={(props) => (
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <span>{props.name}</span>
      <small style={{ color: '#999' }}>({props.category})</small>
    </div>
  )}
  valueTemplate={(props) => <span>{props.name}</span>}
  placeholder="Select item"
/>

Common Patterns

Pattern 1: Self-Referential Data Binding

const data = [
  { id: 1, name: 'Discover Music', hasChild: true, expanded: true },
  { id: 2, pid: 1, name: 'Hot Singles' },
  { id: 3, pid: 1, name: 'Rising Artists' },
  { id: 7, name: 'Sales and Events', hasChild: true },
  { id: 8, pid: 7, name: '100 Albums' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

Pattern 2: Event Handling for Selection Changes

const handleChange = (args) => {
  console.log('Old values:', args.oldValue); // string[]
  console.log('New values:', args.value); // string[]
  console.log('User interaction:', args.isInteracted); // boolean
};

const handleSelect = (args) => {
  console.log('Action:', args.action); // 'select' or 'unselect'
  console.log('Item data:', args.itemData); // object
};

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  onChange={handleChange}
  onSelect={handleSelect}
/>

Pattern 3: Multi-Select with Auto-Check

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  showCheckBox={true}
  treeSettings={{ autoCheck: true }}
  mode="Default"
  delimiterChar=", "
  placeholder="Select multiple items"
/>

Pattern 4: Lazy Loading for Large Datasets

const remoteData = new DataManager({
  url: 'https://your-api.com/data',
  adaptor: new UrlAdaptor(),
});

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: remoteData, value: 'id', text: 'name', hasChildren: 'hasChild' }}
  treeSettings={{ loadOnDemand: true }}
  placeholder="Loading..."
/>

Pattern 5: Custom Item Styling with IconCss

const data = [
  { id: 1, name: 'Documents', iconCss: 'e-folder', hasChild: true },
  { id: 2, pid: 1, name: 'Resume.pdf', iconCss: 'e-pdf' },
  { id: 3, pid: 1, name: 'Report.docx', iconCss: 'e-docx' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    iconCss: 'iconCss',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

Pattern 6: RTL & Localization Support

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  enableRtl={true}
  locale="ar"
  placeholder="اختر عنصرا"
/>

Key Props Overview

id

fields

placeholder

enabled

showCheckBox

showSelectAll

selectAllText

unSelectAllText

allowMultiSelection

itemTemplate

valueTemplate

headerTemplate

footerTemplate

noRecordsTemplate

actionFailureTemplate

allowFiltering

filterType

filterBarPlaceholder

ignoreCase

ignoreAccent

treeSettings

mode

delimiterChar

customTemplate

locale

enableRtl

enablePersistence

cssClass

width

popupHeight

htmlAttributes

Decision Guide

• Local hierarchical - Nested JSON objects with

  child

  property for small-to-medium datasets
• Local self-referential - Flat arrays with

  parentValue

  field for structured data
• Remote with DataManager - OData/Web API for large datasets, dynamic loading, real-time data

• Single select - Default (no checkboxes, no multi-select), read-only visual selection
• Checkboxes -

  showCheckBox={true}

  for explicit multi-selection
• Multi-select -

  allowMultiSelection={true}

  for Ctrl/Shift keyboard selection
• Auto-check - Combine checkboxes with

  treeSettings={{ autoCheck: true }}

  for hierarchy sync

• itemTemplate - Custom formatting per tree item (name + description, icons, badges)
• valueTemplate - Custom display in input field (combined text, formatted values)
• headerTemplate - Static controls above list (instructions, search help, custom controls)
• footerTemplate - Static content below list (count summary, action buttons)
• noRecordsTemplate - Empty state when no data or search yields no results
• actionFailureTemplate - Error message when data fetch fails

• Large datasets (1000+ items)
• Performance-critical applications
• Data fetched from remote API with pagination
• Hierarchies with many levels

• Large datasets requiring search
• User-friendly discovery of items
• Reducing cognitive load for selection

Next Steps

• Get started → Read getting-started.md
• Bind data → Read data-binding.md
• Add checkboxes → Read checkbox-selection.md
• Enable filtering → Read multi-selection-filtering.md
• Configure trees → Read tree-settings.md
• Map fields → Read field-mapping.md
• Customize → Read templates.md
• Access APIs → Read advanced-features.md
• Enhance UX → Read accessibility-localization.md