syncfusion-react-treegrid

Syncfusion React TreeGrid

A comprehensive skill for implementing and customizing Syncfusion's React TreeGrid component. TreeGrid visualizes self-referential hierarchical data in a tabular layout with expand/collapse functionality, enterprise features like virtual scrolling, and comprehensive export options.

Table of Contents

• When to Use This Skill
• TreeGrid Overview
• Data Structure Rules
• Documentation Navigation Guide
• Quick Start Example

When to Use This Skill

Use this skill when you need to:

• Display hierarchical or tree-structured data (organizational charts, file systems, bill of materials)
• Configure columns with proper data binding and formatting
• Implement data editing (cell, row, dialog, batch, template modes)
• Add sorting, filtering, and searching capabilities
• Handle row and cell operations (selection, templates, spanning)
• Optimize performance with virtual scrolling or infinite scrolling
• Configure paging and scrolling strategies
• Export data to PDF, Excel, or CSV formats
• Implement state persistence and aggregation
• Customize appearance with themes and styling
• Support accessibility and internationalization (RTL, localization)

TreeGrid Overview

The TreeGrid is optimized for displaying self-referential hierarchical data with:

• Auto-expand/collapse functionality for collapsible rows
• Enterprise features: virtual scrolling, aggregates, state persistence
• Adaptive UI for mobile and small screens
• Comprehensive export: PDF, Excel, CSV formats
• Full accessibility: WCAG compliance, keyboard navigation, ARIA support
• Internationalization: RTL support, locale customization

Data Structure Rules

Rule 1: childMapping is MANDATORY for Hierarchical Data

Severity: 🔴 CRITICAL - Grid will not expand/collapse without this

Requirement:

// ✅ REQUIRED - Must match data property name exactly
<TreeGridComponent 
  dataSource={data}
  childMapping='subtasks'>
  <ColumnsDirective>
    {/* Columns */}
  </ColumnsDirective>
</TreeGridComponent>

// ❌ WRONG - Will not work
<TreeGridComponent 
  dataSource={data}>
  {/* No childMapping = No expansion possible */}
</TreeGridComponent>

Data Format:

// ✅ CORRECT - childMapping matches 'subtasks' property
const data = [
  {
    TaskID: 1,
    TaskName: 'Parent',
    subtasks: [  // Must match childMapping value exactly
      { TaskID: 2, TaskName: 'Child' }
    ]
  }
];

Exception: Use idMapping + parentIdMapping for flat parent-child structure:

// Alternative: Flat structure with parent IDs
<TreeGridComponent 
  dataSource={flatData}
  idMapping='TaskID'
  parentIdMapping='ParentID'
  hasChildMapping='isParent'>
</TreeGridComponent>

---

Rule 2: Data Type Matching is MANDATORY

Severity: 🟠 IMPORTANT - Type mismatches cause rendering/sorting issues

Requirement:

// ✅ CORRECT - Type matches column definition
const data = [
  {
    TaskID: 1,              // number type
    TaskName: 'Planning',   // string type
    StartDate: new Date(),  // Date object for date columns
  }
];

// Column definition must match data types
<ColumnsDirective>
  <ColumnDirective field='TaskID' headerText='ID' type='number'></ColumnDirective>
  <ColumnDirective field='TaskName' headerText='Task' type='string'></ColumnDirective>
  <ColumnDirective field='StartDate' headerText='Date' type='date' format='yMd'></ColumnDirective>
</ColumnsDirective>

// ❌ WRONG - Type mismatch
const data = [
  {
    TaskID: '1',            // String instead of number
    StartDate: '02/03/2024' // String instead of Date object
  }
];

Complete Props Reference

📄 Property and Methods: references/programmatic-api.md

📄 Events Reference 📖 references/events-reference.md

• Complete event reference guide
• Data events (actionBegin, actionComplete, actionFailure)
• Editing events (cellEdit, cellSave, beforeEdit)
• Selection events (rowSelected, rowDeselected, cellSelected)
• Expand/collapse events
• Column events (drag, drop, resize, hide, show)
• Row events and utilities

---

Documentation Navigation Guide

Data Binding

📖 references/data-binding.md

• Local vs. remote data sources
• Self-referential parent-child relationships
• DataManager integration
• ExpandStateMapping for initial expand state
• Complex data binding for nested objects

Column Configuration

📖 references/column.md

• Column definitions and field mapping
• Tree column index setup
• Data types and formatting
• Column templates and custom rendering
• Headers and styling
• Foreign key columns

Row Operations

📖 references/row.md

• Row templates and custom rendering
• Row height configuration
• Row spanning
• Detail templates for nested content
• Row drag-and-drop
• Indent and outdent operations

Cell Operations

📖 references/cell.md

• Cell editing
• Cell templates, styling and attributes
• Cell selection
• Cell formatting

Editing

📖 references/editing.md

• Cell editing mode
• Row editing mode
• Dialog editing
• Batch editing
• Template editing
• Validation rules and custom validators
• Command column editing
• Server-side persistence

Sorting

📖 references/sorting.md

• Single and multi-column sorting
• Initial sort order configuration
• Custom sort comparers
• Sorting with templates
• Programmatic sorting

Filtering

📖 references/filtering.md

• Filter bar mode
• Filter menu mode
• Excel-like filtering
• Custom filters
• Programmatic filtering
• Filter templates

Searching

📖 references/searching.md

• Global search across all columns
• Search highlight
• Programmatic search
• Search with templates

Selection

📖 references/selection.md

• Row selection (single and multiple)
• Cell selection
• Checkbox selection
• Selection mode configuration
• Programmatic selection
• Selection change events

Display & Layout (Performance & Presentation)

📄 Paging 📖 references/paging.md

• Pager configuration and options
• Page size settings
• Initial page settings
• Pager template customization
• Programmatic pagination

📄 Scrolling 📖 references/scrolling.md

• Vertical and horizontal scrolling
• Scroll height configuration
• Scroll position control
• Sticky headers
• Responsive scrolling

📄 Frozen Rows and Columns 📖 references/frozen-rows-columns.md

• Freeze header rows
• Freeze columns
• Freeze direction
• Lock columns
• IsFrozen property usage

📄 Virtual Scrolling & Infinite Scrolling 📖 references/virtual-scrolling-infinite-scrolling.md

• Virtual scrolling for large datasets
• Infinite scrolling configuration
• Row height for virtual scroll
• ViewportIndex and ViewportStartIndex
• Performance optimization with virtual scroll

Aggregates

📖 references/aggregates.md

• Standard aggregates (Sum, Average, Min, Max, Count)
• Custom aggregates
• Footer aggregates
• Group aggregates
• Hierarchical aggregates for child data

State Persistence

📖 references/state-persistence.md

• Global state persistence
• Local state persistence
• ExpandState tracking
• Persist sort, filter, and paging
• State restoration on reload

Toolbar

📖 references/toolbar.md

• Built-in toolbar items
• Custom toolbar items
• Toolbar item types (Button, Separator, Dropdown)
• Toolbar item click handling
• Toolbar template customization

Context Menu

📖 references/context-menu.md

• Built-in context menu items
• Custom context menu items
• Menu item click handling
• Copy/Edit/Delete operations
• Header context menu

Adaptive View

📖 references/adaptive-view.md

• Adaptive UI for small screens
• Full-screen dialogs
• Horizontal row rendering
• Responsive column adjustments
• Mobile optimization

Loading Animation

📖 references/loading-animation.md

• Loading indicator display
• Custom loading spinner
• Loading state management
• Spinner animation control

Export & Print

📄 PDF Export 📖 references/pdf-export.md

• PDF export configuration
• Export options (columns, format)
• Headers and footers
• Page orientation and size
• Server-side export
• Exporting hierarchical data

📄 Excel Export 📖 references/excel-export.md

• Excel export configuration
• Export options (columns, formatting)
• Cell styling in export
• Headers and footers
• Server-side export
• Exporting hierarchical levels

📄 Print 📖 references/print.md

• Print configuration
• Print with custom layout
• Print specific ranges
• Print hierarchy levels
• Print preview

Clipboard

📖 references/clipboard.md

• Copy cell content to clipboard
• Copy entire rows
• Paste operations
• Copy hierarchy with levels
• Clipboard event handling

Column Features (Advanced)

📄 Column Reorder 📖 references/column-reorder.md

• Enable column drag-and-drop reordering
• Prevent specific columns from reordering
• Reorder events and callbacks
• Programmatic column reordering

📄 Column Resize 📖 references/column-resize.md

• Enable column drag resize
• Auto-fit columns to content
• Column width constraints (min/max)
• Resize events
• Programmatic width changes
• Save/restore column widths

📄 Column Menu 📖 references/column-menu.md

• Built-in column menu items
• Sort, filter, and column chooser from menu
• Custom menu items
• Menu events and handlers
• Conditional menu items

📄 Column Chooser 📖 references/column-chooser.md

• Toggle column visibility
• Column chooser dialog configuration
• Show/hide columns programmatically
• Column visibility events
• Save/restore column visibility

📄 Command Column 📖 references/command-column.md

• Built-in command buttons (Edit, Delete, Save, Cancel)
• Custom command buttons
• Command click handlers
• Icon customization
• Row action patterns

Server Integration

📖 references/server-integration.md

• Remote data binding with DataManager
• Server-side CRUD operations
• Server-side filtering and sorting
• Server-side paging
• Custom request/response handling
• Error handling strategies
• Batch operations

Validation Patterns

📖 references/validation-patterns.md

• Column validation rules
• Custom validation logic
• Cross-field validation
• Async validation (API calls)
• Server-side validation
• Dialog form validation
• Conditional validation
• Error message display

Performance Optimization

📖 references/performance-optimization.md

• Virtual scrolling for large datasets (100k+ rows)
• Infinite scrolling with caching
• Bundle size optimization
• Disabling unnecessary features
• Server-side operations optimization
• Memoization and rendering optimization
• Template optimization
• Event handler optimization
• Benchmarking and performance monitoring
• Performance checklist

Customization

📖 references/styling-appearance.md

• CSS class customization
• Theme selection (Material, Bootstrap, Fluent, Tailwind)
• CSS variable overrides
• Component-specific styling
• Dark mode support
• Row styling
• Cell styling

Globalization

📖 references/globalization.md

• Internationalization (i18n)
• Localization (l10n) for UI text
• Right-to-left (RTL) support
• Date formatting per locale
• Number formatting per locale
• Currency localization

Accessibility

📖 references/accessibility.md

• WCAG 2.1 Level AA compliance
• Keyboard navigation (all shortcuts)
• ARIA attributes and screen reader support
• Expand/collapse keyboard shortcuts
• Editing keyboard navigation
• Selection shortcuts

Quick Start Example

import React from 'react';
import { TreeGridComponent, ColumnsDirective, ColumnDirective, Inject, Page } from '@syncfusion/ej2-react-treegrid';
import { DataManager, UrlAdaptor } from '@syncfusion/ej2-data';

interface ITreeData {
  TaskID?: number;
  TaskName?: string;
  parentID: number | null;
  Children?: ITreeData[];
}

export default function App() {
  const data: ITreeData[] = [
    {
      TaskID: 1,
      TaskName: 'Planning',
      parentID: null,
      Children: [{ TaskID: 2, TaskName: 'Plan timeline', parentID: 1 }]
    }
  ];

  return (
    <TreeGridComponent
      dataSource={data}
      childMapping="Children"
      treeColumnIndex={1}
      height="auto"
      allowPaging={true}
    >
      <ColumnsDirective>
        <ColumnDirective field="TaskID" headerText="Task ID" width={80} />
        <ColumnDirective field="TaskName" headerText="Task Name" width={160} />
      </ColumnsDirective>
      <Inject services={[Page]} />
    </TreeGridComponent>
  );
}

Core Configuration

Property	Type	Default	Description
dataSource	Array | DataManager	[]	Data source for TreeGrid
childMapping	string	null	Property name for child records (e.g., "Children")
idMapping	string	null	Property name for unique ID (flat data)
parentIdMapping	string	null	Property name for parent ID (flat data)
hasChildMapping	string	null	Property for lazy load indicator
treeColumnIndex	number	0	Column index for tree expand icons
expandStateMapping	string	null	Property for initial expand state