Syncfusion Angular Treemap

Implementing Syncfusion Angular TreeMap

The TreeMap component visualizes hierarchical or grouped data as nested rectangles. Each rectangle represents a data item, and its size is determined by a numeric field mapped through weightValuePath. TreeMaps are useful for displaying structures such as product categories, regional breakdowns, market segments, or any grouped dataset where relative magnitude matters.

When to Use This Skill

• Visualizing hierarchical data: Display grouped or multi-level data such as regions, departments, or product categories
• Multi-level data visualization: Show parent-child relationships using levels and groupPath
• Creating drill-down interfaces: Enable interactive navigation through hierarchy levels
• Color-coding data: Use range, equal, desaturation, palette, or direct color binding
• Adding interactive features: Implement selection, highlight, click, double-click, and right-click interactions
• Customizing appearance: Modify layout, colors, borders, labels, headers, legends, and templates
• Displaying supplementary information: Add labels, tooltips, legends, and formatted values
• Exporting visualizations: Print or export as PNG, JPEG, SVG, or PDF
• International support: Enable RTL, locale-specific number formatting, and culture-aware display
• Accessibility: Improve screen reader support, ARIA naming, contrast, and focus behavior

Documentation and Navigation Guide

Choose your reference based on what you need to accomplish:

API Reference

📄 Read: references/api-reference.md

Getting Started

📄 Read: references/getting-started.md

• Installation and npm package setup
• Importing TreeMapModule
• Creating your first TreeMap component
• Theme and style configuration
• Basic component with simple data

Data Binding

📄 Read: references/data-binding.md

• Binding flat collections
• Grouping data with levels
• Mapping data source properties to TreeMap fields
• Configuring weightValuePath for item sizing
• Dynamic data updates and state-driven binding

Color Mapping

📄 Read: references/color-mapping.md

• Range color mapping for numeric values
• Equal color mapping for category-based colors
• Desaturation color mapping with opacity
• Palette-based coloring
• Direct color binding with colorValuePath
• Gradient colors with leafItemSettings.colorMapping

Drilldown and Navigation

📄 Read: references/drilldown-and-navigation.md

• Enabling drilldown functionality
• Parent-child navigation with levels
• drillDownView behavior
• Breadcrumb navigation
• Drill events (drillStart, drillEnd)
• Resetting to root through application state when needed

Levels and Layout

📄 Read: references/levels-and-layout.md

• Configuring multiple hierarchy levels
• groupPath and grouped rendering
• Layout types (Squarified, SliceAndDiceVertical, SliceAndDiceHorizontal, SliceAndDiceAuto)
• Group spacing and leaf gaps
• Header formatting and styling
• Header templates and header sizing

Labels, Tooltips, and Legend

📄 Read: references/labels-tooltips-legend.md

• Data label configuration and formatting
• Label templates and template positioning
• Handling label intersections and overflow
• Tooltip visibility and formatting
• Custom tooltip templates
• Legend display and configuration
• Coordinating legend with color mapping, selection, and highlight

Selection and Interactivity

📄 Read: references/selection-interactivity.md

• Enabling selection and highlight
• Customizing selection colors and borders
• Legend-based selection and hover interaction
• Click, item-selected, double-click, and right-click events
• Programmatic selection with selectItem(...)
• Managing single-item or multi-item workflows in application state

Print, Export, and Accessibility

📄 Read: references/print-export-accessibility.md

• Print functionality
• Image export (PNG, JPEG, SVG)
• PDF export with orientation options
• Base64 export handling
• WCAG accessibility support
• Screen reader support and ARIA labels
• Contrast and focus considerations

Internationalization

📄 Read: references/internationalization.md

• Right-to-left (RTL) rendering
• Locale configuration and number formatting
• Globalization for labels and tooltips
• Render direction configuration
• Multi-language data binding
• Cultural customization with setCulture() and setCurrencyCode()

Quick Start

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Size"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    #treemap-container {
      display: block;
      width: 100%;
      height: 500px;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Category: 'Electronics', Item: 'Laptops', Size: 150 },
    { Category: 'Electronics', Item: 'Phones', Size: 200 },
    { Category: 'Furniture', Item: 'Chairs', Size: 100 },
    { Category: 'Furniture', Item: 'Tables', Size: 120 }
  ]);

  public levels = [
    { groupPath: 'Category' }
  ];

  public leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Common Patterns

Pattern 1: Basic Hierarchical Visualization

Display grouped hierarchical data using levels and groupPath.

public levels = [
  { groupPath: 'Region', headerFormat: '${Region}' },
  { groupPath: 'Country', headerFormat: '${Country}' }
];

public leafItemSettings = {
  labelPath: 'Country'
};

Pattern 2: Color-Mapped Values

Use range color mapping through rangeColorValuePath and leafItemSettings.colorMapping.

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  rangeColorValuePath="Value"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

public leafItemSettings = {
  labelPath: 'Name',
  colorMapping: [
    { from: 0, to: 50, color: '#3498db' },
    { from: 50, to: 100, color: '#e74c3c' }
  ]
};

Pattern 3: Interactive Drilldown

Enable drilldown with breadcrumb navigation for exploring grouped levels.

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Value"
  [enableDrillDown]="true"
  [enableBreadcrumb]="true"
  breadcrumbConnector=" / "
  [levels]="levels"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

Key Props and Configuration

Implementation Notes

• Prefer TreeMapModule for focused standalone Angular components.
• Use TreeMapLegendService, TreeMapTooltipService, TreeMapSelectionService, TreeMapHighlightService, PrintService, ImageExportService, and PdfExportService only when the corresponding features are enabled.
• For color mapping, configure leafItemSettings.colorMapping and pair it with equalColorValuePath or rangeColorValuePath when needed.
• For programmatic selection, use selectItem(levelOrder, isSelected?) rather than unsupported helper methods.
• For accessibility, rely on TreeMap’s built-in ARIA support, meaningful titles, labels, legends, descriptions, and strong color contrast.
• For keyboard and advanced interaction workflows, provide surrounding Angular controls where needed rather than assuming extra undocumented TreeMap keyboard APIs.

TreeMap API Reference

Base URL: Link

Complete API reference for the Syncfusion Angular TreeMap component.

Component: Syncfusion Angular TreeMap Selector: ejs-treemap Package: @syncfusion/ej2-angular-treemap

Default value rule used below

- If the API explicitly provides a default value, it is shown exactly.

- If the API does not explicitly provide a default value, the default is shown as -.

---

Table of Contents

• TreeMapComponent Class
• TreeMapComponent Properties
• Nested Model Classes
• LevelSettingsModel Class
• LeafItemSettingsModel Class
• LegendSettingsModel Class
• TooltipSettingsModel Class
• SelectionSettingsModel Class
• HighlightSettingsModel Class
• ColorMappingModel Class
• CommonTitleSettingsModel Class
• TitleSettingsModel Class
• SubTitleSettingsModel Class
• InitialDrillSettingsModel Class
• TreeMapAjax Class
• Support Types
• BorderModel Class
• FontModel Class
• MarginModel Class
• Location Class
• Methods
• TreeMapComponent Methods
• Events
• TreeMapComponent Events
• Event Args Interfaces
• Enumerations
• Alignment
• ExportType
• LayoutMode
• SelectionMode
• LegendPosition
• LabelPlacement
• TreeMapTheme
• Other Enum Pages
• Angular Directive Pages
• Standalone API Item Pages

---

TreeMapComponent Class

Class: TreeMapComponent Selector: ejs-treemap Package: @syncfusion/ej2-angular-treemap

Represents the Angular TreeMap component used to visualize both hierarchical and flat data using nested rectangles.

Class page: Link

---

TreeMapComponent Properties

---

Nested Model Classes

LevelSettingsModel Class

Class: LevelSettingsModel Description: Configures grouped hierarchy levels in the TreeMap. Class page: Link

Properties

---

LeafItemSettingsModel Class

Class: LeafItemSettingsModel Description: Configures leaf node appearance, labels, templates, color mapping, and spacing. Class page: Link

Properties

---

LegendSettingsModel Class

Class: LegendSettingsModel Description: Configures legend layout, style, mode, and rendering behavior. Class page: Link

Properties

---

TooltipSettingsModel Class

Class: TooltipSettingsModel Description: Configures tooltip appearance, visibility, formatting, and template rendering. Class page: Link

Properties

---

SelectionSettingsModel Class

Class: SelectionSettingsModel Description: Configures selection behavior and visual style for selected items. Class page: Link

Properties

---

HighlightSettingsModel Class

Class: HighlightSettingsModel Description: Configures hover highlight behavior and visual style. Class page: Link

Properties

---

ColorMappingModel Class

Class: ColorMappingModel Description: Configures TreeMap color mapping rules for leaf items or grouped level items. Class page: Link

Properties

---

CommonTitleSettingsModel Class

Class: CommonTitleSettingsModel Description: Shared title model used by TreeMap title-related configurations. Class page: Link

Properties

---

TitleSettingsModel Class

Class: TitleSettingsModel Description: Configures the TreeMap title. Class page: Link

Properties

---

SubTitleSettingsModel Class

Class: SubTitleSettingsModel Description: Configures the TreeMap subtitle. Class page: Link

Properties

---

InitialDrillSettingsModel Class

Class: InitialDrillSettingsModel Description: Configures the initial drill-down target rendered on first load. Class page: Link

Properties

---

TreeMapAjax Class

Class: TreeMapAjax Description: Specifies the data to be received through Ajax request for TreeMap. Class page: Link

Properties

---

Support Types

BorderModel Class

Class: BorderModel Description: Reusable border model used across TreeMap API objects. Class page: Link

Properties

---

FontModel Class

Class: FontModel Description: Reusable text style model used across TreeMap title, legend, tooltip, label, and header settings. Class page: Link

Properties

---

MarginModel Class

Class: MarginModel Description: Reusable margin model used by the TreeMap container. Class page: Link

Properties

---

Location Class

Class: Location Description: Specifies X/Y location parameters used by custom legend positioning. Class page: Link

Properties

---

Methods

TreeMapComponent Methods

Method Usage Example

import { Component, ViewChild, signal } from '@angular/core';
import {
  TreeMapModule,
  TreeMapComponent as SyncTreeMapComponent,
  PrintService,
  ImageExportService,
  PdfExportService,
  TreeMapSelectionService
} from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  providers: [PrintService, ImageExportService, PdfExportService, TreeMapSelectionService],
  template: `
    <div class="toolbar">
      <button type="button" (click)="selectLaptop()">Select Laptop</button>
      <button type="button" (click)="exportPNG()">Export PNG</button>
      <button type="button" (click)="exportPDF()">Export PDF</button>
      <button type="button" (click)="printTreeMap()">Print</button>
      <button type="button" (click)="destroyTreeMap()">Destroy</button>
    </div>

    <ejs-treemap
      #treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Sales"
      [allowPrint]="true"
      [allowImageExport]="true"
      [allowPdfExport]="true"
      [selectionSettings]="selectionSettings"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    .toolbar {
      display: flex;
      gap: 8px;
      flex-wrap: wrap;
      margin-bottom: 12px;
    }

    #treemap-container {
      display: block;
      width: 100%;
      height: 520px;
    }
  `]
})
export class TreeMapComponent {
  @ViewChild('treemap')
  public treemap?: SyncTreeMapComponent;

  public data = signal([
    { Category: 'Electronics', Product: 'Laptop', Sales: 15000 },
    { Category: 'Electronics', Product: 'Phone', Sales: 12000 },
    { Category: 'Furniture', Product: 'Chair', Sales: 8000 }
  ]);

  public levels = [
    { groupPath: 'Category' }
  ];

  public selectionSettings = {
    enable: true,
    mode: 'Item',
    fill: '#dbeafe',
    border: { color: '#2563eb', width: 1 }
  };

  public leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };

  public selectLaptop(): void {
    this.treemap?.selectItem(['Electronics', 'Laptop'], true);
  }

  public exportPNG(): void {
    this.treemap?.export('PNG', 'treemap');
  }

  public exportPDF(): void {
    this.treemap?.export('PDF', 'treemap');
  }

  public printTreeMap(): void {
    this.treemap?.print();
  }

  public destroyTreeMap(): void {
    this.treemap?.destroy();
  }
}

---

Events

TreeMapComponent Events

---

Event Args Interfaces

These are the dedicated API item pages for TreeMap event-args interfaces.

• IClickEventArgs — Link
• IDoubleClickEventArgs — Link
• IDrillEndEventArgs — Link
• IDrillStartEventArgs — Link
• IItemClickEventArgs — Link
• IItemHighlightEventArgs — Link
• IItemMoveEventArgs — Link
• IItemRenderingEventArgs — Link
• IItemSelectedEventArgs — Link
• ILegendItemRenderingEventArgs — Link
• ILegendRenderingEventArgs — Link
• ILoadedEventArgs — Link
• ILoadEventArgs — Link
• IMouseMoveEventArgs — Link
• IPrintEventArgs — Link
• IResizeEventArgs — Link
• IRightClickEventArgs — Link
• ITreeMapTooltipRenderEventArgs — Link

Event Usage Example

import { Component, signal } from '@angular/core';
import {
  TreeMapModule,
  TreeMapTooltipService,
  TreeMapLegendService,
  TreeMapSelectionService,
  TreeMapHighlightService,
  IItemClickEventArgs,
  IItemRenderingEventArgs,
  IDoubleClickEventArgs,
  IDrillStartEventArgs,
  IDrillEndEventArgs,
  IItemSelectedEventArgs,
  ILegendRenderingEventArgs,
  ILegendItemRenderingEventArgs,
  ILoadedEventArgs,
  ILoadEventArgs,
  IMouseMoveEventArgs,
  IResizeEventArgs,
  ITreeMapTooltipRenderEventArgs
} from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  providers: [
    TreeMapTooltipService,
    TreeMapLegendService,
    TreeMapSelectionService,
    TreeMapHighlightService
  ],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Sales"
      equalColorValuePath="Category"
      [enableDrillDown]="true"
      [legendSettings]="legendSettings"
      [tooltipSettings]="tooltipSettings"
      [selectionSettings]="selectionSettings"
      [highlightSettings]="highlightSettings"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings"
      (load)="onLoad($event)"
      (loaded)="onLoaded($event)"
      (itemRendering)="onItemRendering($event)"
      (click)="onClick($event)"
      (itemClick)="onItemClick($event)"
      (doubleClick)="onDoubleClick($event)"
      (drillStart)="onDrillStart($event)"
      (drillEnd)="onDrillEnd($event)"
      (itemSelected)="onItemSelected($event)"
      (legendRendering)="onLegendRendering($event)"
      (legendItemRendering)="onLegendItemRendering($event)"
      (mouseMove)="onMouseMove($event)"
      (itemMove)="onItemMove($event)"
      (itemHighlight)="onItemHighlight($event)"
      (rightClick)="onRightClick($event)"
      (tooltipRendering)="onTooltipRendering($event)"
      (resize)="onResize($event)">
    </ejs-treemap>

    <div class="event-log">
      <h3>Last Event</h3>
      <p>{{ lastEvent() }}</p>
    </div>
  `,
  styles: [`
    #treemap-container {
      display: block;
      width: 100%;
      height: 520px;
    }

    .event-log {
      margin-top: 12px;
      padding: 12px;
      border: 1px solid #d1d5db;
      border-radius: 8px;
      background: #f9fafb;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Category: 'Electronics', Product: 'Laptop', Sales: 15000 },
    { Category: 'Electronics', Product: 'Phone', Sales: 12000 },
    { Category: 'Furniture', Product: 'Chair', Sales: 8000 },
    { Category: 'Clothing', Product: 'Shirt', Sales: 5000 }
  ]);

  public levels = [{ groupPath: 'Category' }];

  public leafItemSettings = {
    labelPath: 'Product',
    colorMapping: [
      { value: 'Electronics', color: '#2563eb', label: 'Electronics' },
      { value: 'Furniture', color: '#16a34a', label: 'Furniture' },
      { value: 'Clothing', color: '#ea580c', label: 'Clothing' }
    ]
  };

  public legendSettings = {
    visible: true
  };

  public tooltipSettings = {
    visible: true,
    format: '${Product}: ${Sales}'
  };

  public selectionSettings = {
    enable: true,
    mode: 'Item',
    fill: '#dbeafe',
    border: { color: '#2563eb', width: 1 }
  };

  public highlightSettings = {
    enable: true,
    fill: '#fde68a',
    border: { color: '#d97706', width: 1 }
  };

  public lastEvent = signal('No event yet.');

  public onLoad(args: ILoadEventArgs): void {
    this.lastEvent.set('load');
    console.log('load', args);
  }

  public onLoaded(args: ILoadedEventArgs): void {
    this.lastEvent.set('loaded');
    console.log('loaded', args);
  }

  public onItemRendering(args: IItemRenderingEventArgs): void {
    this.lastEvent.set('itemRendering');
    console.log('itemRendering', args);
  }

  public onClick(args: IItemClickEventArgs): void {
    this.lastEvent.set('click');
    console.log('click', args);
  }

  public onItemClick(args: IItemClickEventArgs): void {
    this.lastEvent.set('itemClick');
    console.log('itemClick', args);
  }

  public onDoubleClick(args: IDoubleClickEventArgs): void {
    this.lastEvent.set('doubleClick');
    console.log('doubleClick', args);
  }

  public onDrillStart(args: IDrillStartEventArgs): void {
    this.lastEvent.set('drillStart');
    console.log('drillStart', args);
  }

  public onDrillEnd(args: IDrillEndEventArgs): void {
    this.lastEvent.set('drillEnd');
    console.log('drillEnd', args);
  }

  public onItemSelected(args: IItemSelectedEventArgs): void {
    this.lastEvent.set('itemSelected');
    console.log('itemSelected', args);
  }

  public onLegendRendering(args: ILegendRenderingEventArgs): void {
    this.lastEvent.set('legendRendering');
    console.log('legendRendering', args);
  }

  public onLegendItemRendering(args: ILegendItemRenderingEventArgs): void {
    this.lastEvent.set('legendItemRendering');
    console.log('legendItemRendering', args);
  }

  public onMouseMove(args: IMouseMoveEventArgs): void {
    this.lastEvent.set('mouseMove');
    console.log('mouseMove', args);
  }

  public onItemMove(args: any): void {
    this.lastEvent.set('itemMove');
    console.log('itemMove', args);
  }

  public onItemHighlight(args: any): void {
    this.lastEvent.set('itemHighlight');
    console.log('itemHighlight', args);
  }

  public onRightClick(args: IMouseMoveEventArgs): void {
    this.lastEvent.set('rightClick');
    console.log('rightClick', args);
  }

  public onTooltipRendering(args: ITreeMapTooltipRenderEventArgs): void {
    this.lastEvent.set('tooltipRendering');
    console.log('tooltipRendering', args);
  }

  public onResize(args: IResizeEventArgs): void {
    this.lastEvent.set('resize');
    console.log('resize', args);
  }
}

---

## Enumerations

### Alignment

Specifies the alignment of the elements in the TreeMap.

export type Alignment = | 'Near' | 'Center' | 'Far';

**Common values:**
- `Near`
- `Center`
- `Far`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/alignment)

---

### ExportType

Specifies the export type for the TreeMap.

export type ExportType = | 'PNG' | 'JPEG' | 'SVG' | 'PDF';

**Common values:**
- `PNG`
- `JPEG`
- `SVG`
- `PDF`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/exporttype)

---

### HighLightMode

Specifies the element that must be highlighted when mouse over is performed in the TreeMap.

export type HighLightMode = | 'Item' | 'Child' | 'Parent' | 'All';

**Common values:**
- `Item` — highlights the hovered item
- `Child` — highlights child items
- `Parent` — highlights the parent group
- `All` — highlights the full related hierarchy

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/highlightmode)

---

### LabelAlignment

Defines the action of the label to be placed within the defined margins.

export type LabelAlignment = | 'Trim' | 'Hide' | 'WrapByWord' | 'Wrap';

**Common values:**
- `Trim` — trims the label if it exceeds the available bounds
- `Hide` — hides the label if it exceeds the available bounds
- `WrapByWord` — wraps the label by words
- `Wrap` — wraps the label

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/labelalignment)

---

### LabelIntersectAction

Defines the action to perform when labels intersect each other in the TreeMap.

export type LabelIntersectAction = | 'None' | 'Trim' | 'Hide';

**Common values:**
- `None` — shows all labels without applying collision handling
- `Trim` — trims labels when they intersect
- `Hide` — hides labels when they intersect

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/labelintersectaction)

---

### LabelPlacement

Defines the placement type of the label.

export type LabelPlacement = | 'Before' | 'After';

**Common values:**
- `Before`
- `After`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/labelplacement)

---

### LabelPosition

Defines the position of the label in the TreeMap leaf node.

export type LabelPosition = | 'TopLeft' | 'TopCenter' | 'TopRight' | 'CenterLeft' | 'Center' | 'CenterRight' | 'BottomLeft' | 'BottomCenter' | 'BottomRight';

**Common values:**
- `TopLeft`
- `TopCenter`
- `TopRight`
- `CenterLeft`
- `Center`
- `CenterRight`
- `BottomLeft`
- `BottomCenter`
- `BottomRight`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/labelposition)

---

### LayoutMode

Specifies the layout rendering mode of the TreeMap.

export type LayoutMode = | 'Squarified' | 'SliceAndDiceHorizontal' | 'SliceAndDiceVertical' | 'SliceAndDiceAuto';

**Common values:**
- `Squarified` — default balanced layout
- `SliceAndDiceHorizontal` — slices items horizontally
- `SliceAndDiceVertical` — slices items vertically
- `SliceAndDiceAuto` — automatically chooses slice direction

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/layoutmode)

---

### LegendMode

Defines the modes for rendering the legend.

export type LegendMode = | 'Default' | 'Interactive';

**Common values:**
- `Default` — standard legend rendering
- `Interactive` — interactive legend rendering

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/legendmode)

---

### LegendOrientation

Specifies the orientation of the legend in the TreeMap.

export type LegendOrientation = | 'None' | 'Horizontal' | 'Vertical';

**Common values:**
- `None`
- `Horizontal`
- `Vertical`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/legendorientation)

---

### LegendPosition

Controls where the legend is placed relative to the TreeMap.

export type LegendPosition = | 'Top' | 'Bottom' | 'Left' | 'Right' | 'Float';

**Common values:**
- `Top`
- `Bottom`
- `Left`
- `Right`
- `Float`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/legendposition)

---

### LegendShape

Defines the shape of the legend item in the TreeMap.

export type LegendShape = | 'Circle' | 'Rectangle' | 'Triangle' | 'Diamond' | 'Cross' | 'Star' | 'HorizontalLine' | 'VerticalLine' | 'Pentagon' | 'InvertedTriangle' | 'Image';

**Common values:**
- `Circle`
- `Rectangle`
- `Triangle`
- `Diamond`
- `Cross`
- `Star`
- `HorizontalLine`
- `VerticalLine`
- `Pentagon`
- `InvertedTriangle`
- `Image`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/legendshape)

---

### RenderingMode

Defines the rendering directions used to render TreeMap items.

export type RenderingMode = | 'TopRightBottomLeft' | 'BottomLeftTopRight' | 'BottomRightTopLeft' | 'TopLeftBottomRight';

**Common values:**
- `TopRightBottomLeft`
- `BottomLeftTopRight`
- `BottomRightTopLeft`
- `TopLeftBottomRight`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/renderingmode)

---

### SelectionMode

Specifies which TreeMap element is selected when the user interacts with the component.

export type SelectionMode = | 'Item' | 'Child' | 'Parent' | 'All';

**Common values:**
- `Item` — selects the clicked item
- `Child` — selects child items
- `Parent` — selects the parent group
- `All` — selects the full related hierarchy

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/selectionmode)

---

### TreeMapTheme

Defines the built-in theme supported for TreeMap.

export type TreeMapTheme = | 'Material' | 'Fabric' | 'HighContrastLight' | 'Bootstrap' | 'MaterialDark' | 'FabricDark' | 'HighContrast' | 'BootstrapDark' | 'Bootstrap4' | 'Tailwind' | 'TailwindDark' | 'Tailwind3' | 'Tailwind3Dark' | 'Bootstrap5' | 'Bootstrap5Dark' | 'Fluent' | 'FluentDark' | 'Material3' | 'Material3Dark' | 'Fluent2' | 'Fluent2Dark' | 'Fluent2HighContrast';

**Common values:**
- `Material`
- `Fabric`
- `HighContrastLight`
- `Bootstrap`
- `MaterialDark`
- `FabricDark`
- `HighContrast`
- `BootstrapDark`
- `Bootstrap4`
- `Tailwind`
- `TailwindDark`
- `Tailwind3`
- `Tailwind3Dark`
- `Bootstrap5`
- `Bootstrap5Dark`
- `Fluent`
- `FluentDark`
- `Material3`
- `Material3Dark`
- `Fluent2`
- `Fluent2Dark`
- `Fluent2HighContrast`

**Reference:** [Link](https://ej2.syncfusion.com/angular/documentation/api/treemap/treemaptheme)

Color Mapping in Angular TreeMap

Table of Contents

• Overview
• Range Color Mapping
• Basic Range Mapping
• Color Range Examples
• Equal Color Mapping
• Category-Based Coloring
• Desaturation Color Mapping
• Opacity-Based Coloring
• Palette Color Mapping
• Simple Palette Assignment
• Multiple Gradient Colors
• Gradient Color Mapping
• Direct Color Assignment
• Color Value Path
• Color Mapping for Group Headers
• Group vs Leaf Coloring
• Color Mapping Best Practices
• DO: Use Accessible Color Ranges
• DON'T: Use Similar Colors for Different Ranges
• DO: Align Colors with Data Meaning
• DO: Use Sequential Colors for Ranges
• Troubleshooting
• Final Notes

Overview

Color mapping in the Syncfusion Angular TreeMap is a built-in feature set used to customize the fill color of leaf items based on numeric ranges, exact values, opacity variation, palette assignment, gradients, or a color field from the data source.

The original content was mostly correct, but a few definitions and examples needed to be adjusted so they better match the built-in TreeMap API and modern Angular usage.

Range Color Mapping

Range color mapping is a built-in TreeMap coloring mode used to apply colors based on numeric value intervals. It works by binding a numeric field to rangeColorValuePath and defining from, to, and color entries inside leafItemSettings.colorMapping.

Basic Range Mapping

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Sales"
      rangeColorValuePath="Profit"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'A', Sales: 15000, Profit: 35 },
    { Product: 'B', Sales: 12000, Profit: 55 },
    { Product: 'C', Sales: 8000, Profit: 75 },
    { Product: 'D', Sales: 10000, Profit: 20 }
  ]);

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 },
    colorMapping: [
      { from: 0, to: 25, color: '#a6c84c' },
      { from: 25, to: 50, color: '#f1b41d' },
      { from: 50, to: 75, color: '#f18f17' },
      { from: 75, to: 100, color: '#c1272d' }
    ]
  };
}

Key Properties:

• rangeColorValuePath: The numeric field used for evaluating range-based colors.
• from: The lower boundary of the color range.
• to: The upper boundary of the color range.
• color: The fill color applied when the data value falls inside that range.

Color Range Examples

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    { from: -10, to: 0, color: '#0066cc' },
    { from: 0, to: 15, color: '#3399ff' },
    { from: 15, to: 25, color: '#66cc00' },
    { from: 25, to: 40, color: '#ff6600' },
    { from: 40, to: 60, color: '#cc0000' }
  ]
};

This is useful for temperature bands, risk scoring, sales tiers, or any metric where the numeric scale itself carries meaning.

Equal Color Mapping

Equal color mapping is another built-in TreeMap coloring mode. It is used when the color should depend on exact category values rather than numeric intervals.

Category-Based Coloring

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      equalColorValuePath="Category"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'Laptop', Sales: 15000, Category: 'Electronics' },
    { Product: 'Chair', Sales: 8000, Category: 'Furniture' },
    { Product: 'Shirt', Sales: 5000, Category: 'Clothing' }
  ]);

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 },
    colorMapping: [
      { value: 'Electronics', color: '#0066cc' },
      { value: 'Furniture', color: '#66cc00' },
      { value: 'Clothing', color: '#ff6600' }
    ]
  };
}

Key Properties:

• equalColorValuePath: The field that contains the exact value to compare.
• value: The specific category or value to match.
• color: The fill color assigned to matched items.

This is the best option for category-based visuals such as brand, status, department, or product type.

Desaturation Color Mapping

Desaturation color mapping is built in and uses minOpacity and maxOpacity to show value intensity. It still works through the color-mapping configuration, but instead of switching between very different colors, it varies opacity across the range.

Opacity-Based Coloring

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      rangeColorValuePath="Profit"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'A', Sales: 15000, Profit: 10 },
    { Product: 'B', Sales: 12000, Profit: 30 },
    { Product: 'C', Sales: 8000, Profit: 60 },
    { Product: 'D', Sales: 10000, Profit: 90 }
  ]);

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 },
    colorMapping: [
      {
        from: 0,
        to: 100,
        color: '#0066cc',
        minOpacity: 0.2,
        maxOpacity: 1
      }
    ]
  };
}

Key Properties:

• color: The base color used for the opacity transition.
• minOpacity: The opacity used near the low end of the range.
• maxOpacity: The opacity used near the high end of the range.

Use Case: Items with lower profit or lower score appear lighter, while higher values appear more visually prominent.

Palette Color Mapping

Palette coloring is built in, but it is not the same as range or equal color mapping. Instead of comparing values, TreeMap cycles through the colors you provide in the palette property.

Simple Palette Assignment

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      [palette]="palette"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'A', Sales: 15000 },
    { Product: 'B', Sales: 12000 },
    { Product: 'C', Sales: 8000 },
    { Product: 'D', Sales: 10000 },
    { Product: 'E', Sales: 9000 }
  ]);

  palette = ['#0066cc', '#66cc00', '#ff6600', '#cc0000', '#9933ff'];

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Behavior: TreeMap assigns colors from the palette in sequence across the rendered items.

This is ideal when you simply want quick visual distinction between items without a value-based mapping rule.

Multiple Gradient Colors

This is a built-in TreeMap capability. Syncfusion supports giving an array of colors inside a colorMapping entry so the component can apply a gradient-like effect within the configured range.

Gradient Color Mapping

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      rangeColorValuePath="Score"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'A', Sales: 15000, Score: 10 },
    { Product: 'B', Sales: 12000, Score: 35 },
    { Product: 'C', Sales: 8000, Score: 65 },
    { Product: 'D', Sales: 10000, Score: 90 }
  ]);

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 },
    colorMapping: [
      { from: 0, to: 50, color: ['#3398db', '#7cb5ec', '#ffd700'] },
      { from: 50, to: 100, color: ['#ffd700', '#ff8c42', '#d32f2f'] }
    ]
  };
}

Colors transition across the provided color array for values within each range.

Direct Color Assignment

Direct color assignment is also built in. If your data source already contains the final color for each item, bind that field to colorValuePath.

Color Value Path

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      colorValuePath="Color"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Product: 'A', Sales: 15000, Color: '#0066cc' },
    { Product: 'B', Sales: 12000, Color: '#66cc00' },
    { Product: 'C', Sales: 8000, Color: '#ff6600' }
  ]);

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

When to use: Use this when color is already part of the dataset and should not be derived by TreeMap rules.

Color Mapping for Group Headers

This section should be defined more precisely: TreeMap supports styling for group headers, but this is not the same as leaf-item color mapping. Group styling is usually applied through levels, while leaf-item styling is controlled through leafItemSettings, palette, or color mapping properties.

Group vs Leaf Coloring

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Value"
      [levels]="levels()"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Category: 'Electronics', Item: 'Laptop', Value: 25 },
    { Category: 'Electronics', Item: 'Phone', Value: 20 },
    { Category: 'Furniture', Item: 'Chair', Value: 15 },
    { Category: 'Furniture', Item: 'Table', Value: 18 }
  ]);

  levels = signal([
    {
      groupPath: 'Category',
      fill: '#dbeafe',
      border: { color: '#93c5fd', width: 1 }
    }
  ]);

  leafItemSettings = {
    labelPath: 'Item',
    fill: '#0066cc',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Clarified Behavior: Group headers are styled through levels, while leaf items are styled through leafItemSettings and the built-in color mechanisms.

Color Mapping Best Practices

DO: Use Accessible Color Ranges

Choose colors with enough contrast so users can distinguish them clearly.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    { from: 0, to: 15, color: '#0066cc' },
    { from: 15, to: 50, color: '#ff6600' }
  ]
};

DON'T: Use Similar Colors for Different Ranges

Avoid ranges that are visually too close together, because users may not be able to distinguish them quickly.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    { from: 0, to: 50, color: '#0066cc' },
    { from: 50, to: 100, color: '#0055bb' }
  ]
};

DO: Align Colors with Data Meaning

Use color semantics that support the data meaning.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    { from: 0, to: 40, color: '#cc0000' },
    { from: 40, to: 80, color: '#ffcc00' },
    { from: 80, to: 100, color: '#00cc00' }
  ]
};

DO: Use Sequential Colors for Ranges

For progressive values such as score, revenue, density, or completion, use a visually ordered sequence.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    {
      from: 0,
      to: 100,
      color: ['#e8f4f8', '#b3d9e6', '#7eb8d4', '#5a9bc0']
    }
  ]
};

Troubleshooting

Issue: Color mapping is not applying.

Updated Definition: In Syncfusion TreeMap, range and equal mapping are commonly configured through leafItemSettings.colorMapping. Make sure the correct value path is bound at the TreeMap level and the field exists in the data source.

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Sales"
  rangeColorValuePath="Profit"
  [leafItemSettings]="leafItemSettings">
</ejs-treemap>

Issue: All items show the same color.

Possible Causes:

• All values fall into the same defined range.
• Exact match values do not match the value entries in equal mapping.
• palette is being used when you expected rule-based mapping.
• colorValuePath points to the wrong field name.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    { from: 0, to: 100, color: '#0066cc' }
  ]
};

Issue: Colors appear washed out.

Updated Definition: This is expected if minOpacity is too low. Increase the minimum opacity or use stronger base colors.

leafItemSettings = {
  labelPath: 'Product',
  colorMapping: [
    {
      from: 0,
      to: 100,
      color: '#0066cc',
      minOpacity: 0.5,
      maxOpacity: 1
    }
  ]
};

Final Notes

• Keep TreeMapAllModule only if you intentionally want the full bundled module style shown in some documentation samples. For focused standalone components, TreeMapModule is usually cleaner.
• Do not remove palette, gradient, direct color binding, or desaturation from the document because they are built into the Syncfusion TreeMap component.
• The main correction is not feature removal, but using the right built-in configuration pattern and clearer definitions.

Data Binding in Angular TreeMap

Table of Contents

• Overview
• Flat Collection Binding
• Basic Flat Collection
• Weighted Collection
• Hierarchical Collection Binding
• Two-Level Hierarchy
• Multi-Level Hierarchy (3+ Levels)
• Data Source Properties Mapping
• Dynamic Data Updates
• Recommended Angular Update Pattern
• Structured Hierarchical Objects
• Nested Source Example
• Flatten Before Binding
• Data Format Best Practices
• DO: Clear Field Names
• DON'T: Ambiguous Field Names
• DO: Consistent Data Types
• DON'T: Mixed Data Types
• Troubleshooting

Overview

The Syncfusion Angular TreeMap binds data through the dataSource property. In practice, TreeMap rendering is driven by a collection of items plus one required numeric field mapped through weightValuePath. You can bind simple flat collections directly, and you can visualize grouped or hierarchical relationships by configuring levels with groupPath fields over the bound data.

Flat Collection Binding

Use a flat collection when your dataset is a single list of items and each rectangle is represented directly by one data object.

Basic Flat Collection

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Size"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Item: 'Laptop', Size: 150 },
    { Item: 'Phone', Size: 200 },
    { Item: 'Tablet', Size: 100 },
    { Item: 'Watch', Size: 50 }
  ]);

  leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Weighted Collection

Use weightValuePath to specify the numeric field that determines the area of each leaf item.

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Sales">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
    data = signal([
        { Product: 'A', Sales: 15000, Category: 'Electronics' },
        { Product: 'B', Sales: 12000, Category: 'Electronics' },
        { Product: 'C', Sales: 8000, Category: 'Furniture' }
      ]);

}

Key Point: Items with larger numeric values in the weightValuePath field render as larger rectangles.

Hierarchical Collection Binding

For TreeMap, hierarchy is commonly represented by grouping fields in the data source and then mapping those fields with levels and groupPath. This means the data is often still a flat array, but TreeMap renders it as grouped hierarchy.

Two-Level Hierarchy

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Value"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Mexico', Value: 1286 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 }
  ]);

  levels = [
    { groupPath: 'Region' },
    { groupPath: 'Country' }
  ];

  leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Multi-Level Hierarchy (3+ Levels)

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Value"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Continent: 'North America', Region: 'Canada', Country: 'Toronto', Value: 500 },
    { Continent: 'North America', Region: 'USA', Country: 'California', Value: 800 },
    { Continent: 'Europe', Region: 'Western', Country: 'France', Value: 600 }
  ]);

  levels = [
    { groupPath: 'Continent', headerFormat: '${Continent}' },
    { groupPath: 'Region', headerFormat: '${Region}' },
    { groupPath: 'Country', headerFormat: '${Country}' }
  ];

  leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Clarified Definition: In TreeMap, this is still typically a grouped data-source approach. The hierarchy is rendered from field mappings, not from a TreeView-style recursive UI binding pattern.

Data Source Properties Mapping

Map your data fields carefully to the TreeMap properties that control size, grouping, labels, and optional color behavior.

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      [dataSource]="data()"
      weightValuePath="Sales"
      colorValuePath="Color"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  data = signal([
    { Department: 'Electronics', Product: 'Laptop', Sales: 15000, Color: '#2563eb' },
    { Department: 'Electronics', Product: 'Phone', Sales: 12000, Color: '#16a34a' },
    { Department: 'Furniture', Product: 'Chair', Sales: 8000, Color: '#ea580c' }
  ]);

  levels = [
    { groupPath: 'Department' }
  ];

  leafItemSettings = {
    labelPath: 'Product',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Common mappings:

• dataSource: The collection bound to the TreeMap.
• weightValuePath: The numeric field that controls leaf size.
• labelPath in leafItemSettings: The field displayed as the leaf label.
• groupPath in levels: The field used to form grouped hierarchy.
• colorValuePath: Optional direct color field from the data source.
• equalColorValuePath: Optional field used for exact-match color mapping.
• rangeColorValuePath: Optional field used for numeric range color mapping.

Important: Do not treat colorValuePath, equalColorValuePath, and rangeColorValuePath as if they all need to be enabled together. They represent different coloring strategies and should be used intentionally.

Dynamic Data Updates

TreeMap data can be updated after initialization. In Angular, the cleanest approach is to replace the bound collection reference. This works well with Signals and keeps the update flow declarative.

Recommended Angular Update Pattern

import { Component, signal, ViewChild } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <button type="button" (click)="updateData()">Update Data</button>

    <ejs-treemap
      #treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Value"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  treemap = ViewChild('treemap');

  data = signal([
    { Item: 'A', Value: 100 },
    { Item: 'B', Value: 200 }
  ]);

  leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };

  updateData(): void {
    this.data.set([
      { Item: 'A', Value: 150 },
      { Item: 'B', Value: 250 },
      { Item: 'C', Value: 180 }
    ]);

    const instance = this.treemap();
    if (instance) {
      instance.refresh();
    }
  }
}

Updated Definition: If your Angular wrapper already reacts properly to a new array reference, a manual refresh() may not always be necessary. It is still reasonable to keep it when you want to force immediate redraw behavior after imperative changes.

Structured Hierarchical Objects

If your source data is deeply nested with children arrays, that structure is not the most TreeMap-friendly binding format for grouped levels rendering. Instead of binding the nested structure directly as-is, preprocess it into a flattened collection that contains the grouping fields TreeMap expects.

Nested Source Example

nestedData = [
  {
    id: '1',
    name: 'Electronics',
    children: [
      { id: '1a', name: 'Laptops', value: 150 },
      { id: '1b', name: 'Phones', value: 200 }
    ]
  },
  {
    id: '2',
    name: 'Furniture',
    children: [
      { id: '2a', name: 'Chairs', value: 100 },
      { id: '2b', name: 'Tables', value: 120 }
    ]
  }
];

Flatten Before Binding

import { Component, computed, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

interface ChildItem {
  id: string;
  name: string;
  value: number;
}

interface CategoryItem {
  id: string;
  name: string;
  children: ChildItem[];
}

interface FlattenedItem {
  CategoryId: string;
  Category: string;
  ItemId: string;
  Item: string;
  Value: number;
}

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="flattenedData()"
      weightValuePath="Value"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    :host {
      display: block;
      padding: 12px;
      box-sizing: border-box;
    }

    #treemap-container {
      display: block;
      width: 100%;
      height: 500px;
    }
  `]
})
export class TreeMapComponent {
  public nestedData = signal<CategoryItem[]>([
    {
      id: '1',
      name: 'Electronics',
      children: [
        { id: '1a', name: 'Laptops', value: 150 },
        { id: '1b', name: 'Phones', value: 200 }
      ]
    },
    {
      id: '2',
      name: 'Furniture',
      children: [
        { id: '2a', name: 'Chairs', value: 100 },
        { id: '2b', name: 'Tables', value: 120 }
      ]
    }
  ]);

  public flattenedData = computed<FlattenedItem[]>(() => {
    const result: FlattenedItem[] = [];
    const categories = this.nestedData();

    for (const category of categories) {
      for (const child of category.children) {
        result.push({
          CategoryId: category.id,
          Category: category.name,
          ItemId: child.id,
          Item: child.name,
          Value: child.value
        });
      }
    }

    return result;
  });

  public levels = [
    {
      groupPath: 'Category',
      headerFormat: '${Category}',
      fill: '#dbeafe',
      border: { color: '#93c5fd', width: 1 }
    }
  ];

  public leafItemSettings = {
    labelPath: 'Item',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Updated Definition: Keep the nested source if that is how your application stores data, but transform it into a flat TreeMap input model before binding.

Data Format Best Practices

DO: Clear Field Names

{ Department: 'Sales', Employee: 'John', Revenue: 5000 }

Use descriptive property names so that weightValuePath, groupPath, labelPath, and optional color mappings are easy to understand and maintain.

DON'T: Ambiguous Field Names

{ d: 'Sales', e: 'John', r: 5000 }

Short unclear field names make configuration harder to read and easier to misconfigure.

DO: Consistent Data Types

{ Item: 'Product A', Sales: 15000 }
{ Item: 'Product B', Sales: 12000 }

The field mapped to weightValuePath should remain numeric for all items.

DON'T: Mixed Data Types

{ Item: 'Product A', Sales: 15000 }
{ Item: 'Product B', Sales: '12000' }

Avoid mixing numbers and strings in the same mapped field. TreeMap size calculations should use a consistent numeric type.

Troubleshooting

Issue: TreeMap not rendering with data

Solution: Ensure weightValuePath points to an existing numeric field.

<ejs-treemap
  [dataSource]="data()"
  weightValuePath="Sales">
</ejs-treemap>

Issue: Hierarchy not displaying correctly

Solution: Verify that every configured groupPath exists in the bound data items and that the field names are consistent.

levels = [
  { groupPath: 'Region' },
  { groupPath: 'Country' }
];

Issue: Labels are empty

Solution: Check that leafItemSettings.labelPath matches a valid field from the data source.

leafItemSettings = {
  labelPath: 'Item'
};

Issue: Data changes not reflecting in TreeMap

Solution: Replace the bound array reference, and if needed, call refresh() after imperative updates.

this.data.set(newData);
this.treemap()?.refresh();

Drilldown and Navigation in Angular TreeMap

Table of Contents

• Overview
• What was corrected without removing built-in Syncfusion features
• Enabling Drilldown
• Basic Drilldown Setup
• Parent-Child Navigation
• Understanding Navigation Flow
• Three-Level Hierarchy Example
• Header Customization at Each Level
• On-Demand Data Loading
• Enable DrillDownView
• Data Structure with On-Demand
• Breadcrumb Navigation
• Enable Breadcrumb
• Breadcrumb Connector Options
• Click Breadcrumb to Navigate Up
• Back Navigation
• Programmatic Back Navigation
• Reset to Root Using Angular State
• Root-Level Detection
• Drill Down Events
• Listen to Drill Down Actions
• Event Properties
• Track Navigation History
• Best Practices
• DO: Use Meaningful Header Formats
• DON'T: Use Unclear Headers
• DO: Include Aggregated Totals
• DO: Provide Visual Feedback
• DO: Limit Hierarchy Depth
• Troubleshooting

Overview

Drilldown in the Syncfusion Angular TreeMap is a built-in navigation feature that lets users move from a higher grouping level to a lower grouping level by clicking items. The original content was mostly correct, but a few definitions and event names needed to be adjusted to better match the built-in Angular TreeMap API.

What was corrected without removing built-in Syncfusion features

• TreeMapAllModule was not removed as a Syncfusion module, but the examples were updated to use TreeMapModule only for cleaner standalone Angular usage.
• The drilldown examples were updated to use normal Angular template markup instead of escaped HTML.
• The event names were corrected from drillDown and drillUp to the documented TreeMap drill events such as drillStart and drillEnd.
• The back-navigation section was redefined because a public Angular TreeMap drillUp() method is not part of the documented API pattern shown for the component. Built-in navigation is primarily handled by clicking the drilled node path and by using breadcrumb support.
• The examples were updated to use modern Angular patterns such as standalone components and Signals.

Enabling Drilldown

Drilldown is enabled by setting enableDrillDown to true. TreeMap then lets the user click a rendered group and move into the next hierarchy level.

Basic Drilldown Setup

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Value"
      [enableDrillDown]="true"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `,
  styles: [`
    :host {
      display: block;
      padding: 12px;
      box-sizing: border-box;
    }

    #treemap-container {
      display: block;
      width: 100%;
      height: 520px;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Canada', Value: 1841 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 },
    { Region: 'Asia', Country: 'China', Value: 17734 },
    { Region: 'Asia', Country: 'Japan', Value: 4909 }
  ]);

  public levels = [
    { groupPath: 'Region', headerFormat: '${Region}' },
    { groupPath: 'Country', headerFormat: '${Country}' }
  ];

  public leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Behavior: Clicking a region drills into the countries grouped inside that region.

Parent-Child Navigation

TreeMap drilldown is driven by grouped hierarchy fields configured through levels. Each click moves from one grouping layer to the next rendered grouping layer.

Understanding Navigation Flow

When drilldown is enabled:

1. The initial view renders the current top grouping level. 2. Clicking a parent group drills into the next configured level. 3. The header updates to reflect the current context. 4. Users can move back through the built-in drill navigation path, especially when breadcrumb is enabled.

Three-Level Hierarchy Example

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Value"
      [enableDrillDown]="true"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  public data = signal([
    { Continent: 'North America', Region: 'Northeast', State: 'New York', Value: 500 },
    { Continent: 'North America', Region: 'Northeast', State: 'Boston', Value: 400 },
    { Continent: 'North America', Region: 'Southwest', State: 'Texas', Value: 600 },
    { Continent: 'Europe', Region: 'Western', State: 'France', Value: 550 }
  ]);

  public levels = [
    { groupPath: 'Continent', headerFormat: '${Continent}' },
    { groupPath: 'Region', headerFormat: '${Region}' },
    { groupPath: 'State', headerFormat: '${State}' }
  ];

  public leafItemSettings = {
    labelPath: 'State',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Navigation Example:

• Click North America to drill into Northeast and Southwest
• Click Northeast to drill into New York and Boston

Header Customization at Each Level

You can customize the header text and style per level using headerFormat and headerStyle.

public levels = [
  {
    groupPath: 'Continent',
    headerFormat: 'Continent: ${Continent}',
    headerStyle: { size: '16px', fontWeight: '600' }
  },
  {
    groupPath: 'Region',
    headerFormat: 'Region: ${Region}',
    headerStyle: { size: '14px', fontWeight: '500' }
  },
  {
    groupPath: 'State',
    headerFormat: 'State: ${State}',
    headerStyle: { size: '12px' }
  }
];

On-Demand Data Loading

drillDownView is a built-in TreeMap property that changes how child items are rendered during drilldown. Instead of rendering all child items immediately, child nodes are rendered during the drilldown process.

Enable DrillDownView

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Value"
      [enableDrillDown]="true"
      [drillDownView]="true"
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  public data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Canada', Value: 1841 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 }
  ]);

  public levels = [
    { groupPath: 'Region' },
    { groupPath: 'Country' }
  ];

  public leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Use Case: This is useful when you want the lower-level items to be rendered only as the user drills into the hierarchy.

Data Structure with On-Demand

The data remains a grouped collection. What changes is how TreeMap renders the drill hierarchy.

public data = signal([
  { Region: 'North America', Country: 'United States', Value: 25460 },
  { Region: 'North America', Country: 'Canada', Value: 1841 },
  { Region: 'Europe', Country: 'Germany', Value: 3846 },
  { Region: 'Europe', Country: 'France', Value: 2781 }
]);

Updated Definition: drillDownView does not require a special server-side lazy-loading contract by itself. It changes the initial rendering behavior so that child items are shown during drill interaction rather than all at once up front.

Breadcrumb Navigation

Breadcrumb support is built in and can be enabled to show the path from the root level to the current drilled level.

Enable Breadcrumb

import { Component, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <ejs-treemap
      id="treemap-container"
      [dataSource]="data()"
      weightValuePath="Value"
      [enableDrillDown]="true"
      [enableBreadcrumb]="true"
      breadcrumbConnector=" -> "
      [levels]="levels"
      [leafItemSettings]="leafItemSettings">
    </ejs-treemap>
  `
})
export class TreeMapComponent {
  public data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Canada', Value: 1841 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 }
  ]);

  public levels = [
    { groupPath: 'Region' },
    { groupPath: 'Country' }
  ];

  public leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };
}

Breadcrumb Connector Options

You can customize the path separator using breadcrumbConnector.

breadcrumbConnector=" / "
breadcrumbConnector=" -> "
breadcrumbConnector=" :: "
breadcrumbConnector=" | "

Click Breadcrumb to Navigate Up

Built-in breadcrumb support shows the navigation path from the root parent to the current level. This is the recommended built-in way to let users move back to earlier levels without relying on undocumented instance methods.

Back Navigation

This section needed the biggest correction.

Programmatic Back Navigation

The earlier sample used a drillUp() instance method and a currentLevel check, but those are not part of the documented Angular TreeMap API pattern shown for the component examples and events. Because of that, the safer guidance is:

• use built-in breadcrumb navigation for moving upward
• use normal drill interaction to return to earlier levels
• if your application needs a dedicated Reset to Root button, recreate the TreeMap view state from Angular rather than calling an undocumented instance API

Reset to Root Using Angular State

The following example adds a Reset to Root button by recreating the TreeMap component through Angular state. This is an application-level workaround, not a special Syncfusion drill-up API.

import { ChangeDetectorRef, Component, inject, signal } from '@angular/core';
import { TreeMapModule } from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <button type="button" (click)="resetToRoot()">Reset to Root</button>

    @if (showTreeMap()) {
      <ejs-treemap
        [id]="treeMapId()"
        [dataSource]="data()"
        weightValuePath="Value"
        [enableDrillDown]="true"
        [enableBreadcrumb]="true"
        breadcrumbConnector=" -> "
        [levels]="levels"
        [leafItemSettings]="leafItemSettings">
      </ejs-treemap>
    }
  `,
  styles: [`
    :host {
      display: block;
      padding: 12px;
      box-sizing: border-box;
    }

    button {
      margin-bottom: 12px;
      padding: 8px 12px;
      border: 1px solid #cbd5e1;
      background: #ffffff;
      border-radius: 8px;
      cursor: pointer;
    }

    ejs-treemap {
      display: block;
      width: 100%;
      height: 520px;
    }
  `]
})
export class TreeMapComponent {
  private cdr = inject(ChangeDetectorRef);

  public showTreeMap = signal(true);
  public treeMapId = signal('treemap-container-0');

  public data = signal([
    { Continent: 'North America', Region: 'Northeast', State: 'New York', Value: 500 },
    { Continent: 'North America', Region: 'Northeast', State: 'Boston', Value: 400 },
    { Continent: 'North America', Region: 'Southwest', State: 'Texas', Value: 600 },
    { Continent: 'Europe', Region: 'Western', State: 'France', Value: 550 }
  ]);

  public levels = [
    { groupPath: 'Continent', headerFormat: '${Continent}' },
    { groupPath: 'Region', headerFormat: '${Region}' },
    { groupPath: 'State', headerFormat: '${State}', showHeader: false }
  ];

  public leafItemSettings = {
    labelPath: 'State',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };

  public resetToRoot(): void {
    this.showTreeMap.set(false);
    this.cdr.detectChanges();

    setTimeout(() => {
      this.treeMapId.set(`treemap-container-${Date.now()}`);
      this.showTreeMap.set(true);
    }, 0);
  }
}

Root-Level Detection

Instead of relying on an undocumented currentLevel instance property, keep root-level UI behavior under your own Angular state if you need custom buttons, analytics, or navigation indicators.

Updated Guidance: Built-in upward navigation should primarily rely on breadcrumb and drill interaction. For custom app-level controls, use Angular state to recreate or control the view.

Drill Down Events

The event names in the original content needed correction.

Listen to Drill Down Actions

Use documented drill events such as drillStart and drillEnd.

import { Component, signal } from '@angular/core';
import {
  TreeMapModule
} from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <div class="page">
      <ejs-treemap
        id="treemap-container"
        [dataSource]="data()"
        weightValuePath="Value"
        [enableDrillDown]="true"
        [enableBreadcrumb]="true"
        breadcrumbConnector=" -> "
        [levels]="levels"
        [leafItemSettings]="leafItemSettings"
        (drillStart)="onDrillStart($event)"
        (drillEnd)="onDrillEnd($event)">
      </ejs-treemap>

      <section class="event-panel">
        <h3>Drill Information</h3>

        <div class="info-grid">
          <div class="info-card">
            <div class="label">Current Action</div>
            <div class="value">{{ currentAction() }}</div>
          </div>

          <div class="info-card">
            <div class="label">Current Item</div>
            <div class="value">{{ currentItem() }}</div>
          </div>

          <div class="info-card">
            <div class="label">Current Level</div>
            <div class="value">{{ currentLevel() }}</div>
          </div>

          <div class="info-card">
            <div class="label">Last Updated</div>
            <div class="value">{{ lastUpdated() }}</div>
          </div>
        </div>

        <div class="summary-box">
          <div class="label">Summary</div>
          <p>{{ currentSummary() }}</p>
        </div>

        <div class="history-box">
          <div class="label">Navigation History</div>

          @if (navigationHistory().length > 0) {
            <ul class="history-list">
              @for (entry of navigationHistory(); track $index) {
                <li>{{ entry }}</li>
              }
            </ul>
          } @else {
            <p class="empty-text">No drill actions yet.</p>
          }
        </div>
      </section>
    </div>
  `,
  styles: [`
    :host {
      display: block;
      padding: 12px;
      box-sizing: border-box;
      font-family: Arial, Helvetica, sans-serif;
      color: #111827;
    }

    .page {
      display: grid;
      gap: 16px;
    }

    #treemap-container {
      display: block;
      width: 100%;
      height: 520px;
    }

    .event-panel {
      border: 1px solid #d1d5db;
      border-radius: 12px;
      padding: 16px;
      background: #f9fafb;
    }

    .event-panel h3 {
      margin: 0 0 12px;
      font-size: 18px;
      font-weight: 600;
    }

    .info-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
      gap: 12px;
      margin-bottom: 16px;
    }

    .info-card,
    .summary-box,
    .history-box {
      border: 1px solid #e5e7eb;
      border-radius: 10px;
      background: #ffffff;
      padding: 12px;
    }

    .label {
      font-size: 12px;
      font-weight: 600;
      color: #6b7280;
      text-transform: uppercase;
      letter-spacing: 0.04em;
      margin-bottom: 6px;
    }

    .value {
      font-size: 15px;
      font-weight: 500;
      color: #111827;
      word-break: break-word;
    }

    .summary-box p,
    .empty-text {
      margin: 0;
      color: #374151;
      line-height: 1.5;
    }

    .history-list {
      margin: 0;
      padding-left: 18px;
    }

    .history-list li {
      margin-bottom: 8px;
      color: #111827;
      line-height: 1.5;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Canada', Value: 1841 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 }
  ]);

  public levels = [
    { groupPath: 'Region', headerFormat: '${Region}' }
  ];

  public leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };

  public currentAction = signal('No action yet');
  public currentItem = signal('N/A');
  public currentLevel = signal('N/A');
  public lastUpdated = signal('N/A');
  public currentSummary = signal('Interact with the TreeMap to see drill details here.');
  public navigationHistory = signal<string[]>([]);

  public onDrillStart(args: any): void {
    this.updateDrillText('Drill Start', args);
  }

  public onDrillEnd(args: any): void {
    this.updateDrillText('Drill End', args);
  }

  private updateDrillText(
    action: string,
    args: any
  ): void {
    const details = this.extractDetails(args);
    const time = this.formatTime(new Date());

    this.currentAction.set(action);
    this.currentItem.set(details.item);
    this.currentLevel.set(details.level);
    this.lastUpdated.set(time);
    this.currentSummary.set(
      `${action} happened for "${details.item}" at level "${details.level}" on ${time}.`
    );

    this.navigationHistory.update((history) => [
      ...history,
      `${action} | Item: ${details.item} | Level: ${details.level} | Time: ${time}`
    ]);
  }

  private extractDetails(
    args: any
  ): { item: string; level: string } {
    const eventArgs = args as any;

    const item =
      eventArgs?.item?.groupName ??
      eventArgs?.item?.name ??
      eventArgs?.groupName ??
      eventArgs?.name ??
      eventArgs?.renderItems?.[0]?.groupName ??
      eventArgs?.renderItems?.[0]?.name ??
      'Unknown Item';

    const level =
      this.readLevelFromOrder(eventArgs?.levelOrderName) ??
      this.readLevelFromOrder(eventArgs?.item?.levelOrderName) ??
      this.readLevelFromOrder(eventArgs?.renderItems?.[0]?.levelOrderName) ??
      this.readNumericLevel(eventArgs?.groupIndex) ??
      this.readNumericLevel(eventArgs?.currentLevel) ??
      'Unknown Level';

    return {
      item: String(item),
      level: String(level)
    };
  }

  private readLevelFromOrder(value: unknown): string | null {
    if (typeof value !== 'string' || !value.trim()) {
      return null;
    }

    const parts = value
      .split('#')
      .map((part) => part.trim())
      .filter(Boolean);

    return parts.length ? parts[parts.length - 1] : value;
  }

  private readNumericLevel(value: unknown): string | null {
    if (typeof value === 'number') {
      return `Level ${value}`;
    }

    return null;
  }

  private formatTime(date: Date): string {
    return date.toLocaleString();
  }
}

Event Properties

The safest guidance is to use the documented event types and inspect the event object in your handler. The exact event payload can vary depending on the drill action and version, so the best pattern is to strongly type the handler and log the incoming object during development.

public onDrillStart(args: IDrillStartEventArgs): void {
  console.log(args);
}

public onDrillEnd(args: IDrillEndEventArgs): void {
  console.log(args);
}

Track Navigation History

If you need app-level drill history, store it in Angular state from the drill events.

import { Component, signal } from '@angular/core';
import {
  TreeMapModule,
  IDrillEndEventArgs
} from '@syncfusion/ej2-angular-treemap';

@Component({
  selector: 'app-treemap',
  standalone: true,
  imports: [TreeMapModule],
  template: `
    <div class="page">
      <ejs-treemap
        id="treemap-container"
        [dataSource]="data()"
        weightValuePath="Value"
        [enableDrillDown]="true"
        [enableBreadcrumb]="true"
        breadcrumbConnector=" -> "
        [levels]="levels"
        [leafItemSettings]="leafItemSettings"
        (drillEnd)="onDrillEnd($event)">
      </ejs-treemap>

      <div class="history-panel">
        <h3>Navigation History</h3>

        @if (navigationHistory().length > 0) {
          <ul class="history-list">
            @for (entry of navigationHistory(); track $index) {
              <li>{{ entry }}</li>
            }
          </ul>
        } @else {
          <p class="empty-text">No drill actions yet.</p>
        }
      </div>
    </div>
  `,
  styles: [`
    :host {
      display: block;
      padding: 12px;
      box-sizing: border-box;
      font-family: Arial, Helvetica, sans-serif;
    }

    .page {
      display: grid;
      gap: 16px;
    }

    #treemap-container {
      display: block;
      width: 100%;
      height: 520px;
    }

    .history-panel {
      border: 1px solid #d1d5db;
      border-radius: 10px;
      padding: 12px;
      background: #f9fafb;
    }

    .history-panel h3 {
      margin: 0 0 12px;
      font-size: 18px;
    }

    .history-list {
      margin: 0;
      padding-left: 18px;
    }

    .history-list li {
      margin-bottom: 8px;
      color: #111827;
      line-height: 1.5;
    }

    .empty-text {
      margin: 0;
      color: #6b7280;
    }
  `]
})
export class TreeMapComponent {
  public data = signal([
    { Region: 'North America', Country: 'United States', Value: 25460 },
    { Region: 'North America', Country: 'Canada', Value: 1841 },
    { Region: 'Europe', Country: 'Germany', Value: 3846 },
    { Region: 'Europe', Country: 'France', Value: 2781 }
  ]);

  public levels = [
    { groupPath: 'Region', headerFormat: '${Region}' }
  ];

  public leafItemSettings = {
    labelPath: 'Country',
    gap: 4,
    border: { color: '#ffffff', width: 1 }
  };

  public navigationHistory = signal<string[]>([]);

  public onDrillEnd(args: IDrillEndEventArgs): void {
    const itemName = this.getDrilledItemName(args);
    const levelName = this.getDrilledLevel(args);
    const timestamp = new Date().toLocaleString();

    this.navigationHistory.update((history) => [
      ...history,
      `Drill completed | Item: ${itemName} | Level: ${levelName} | Time: ${timestamp}`
    ]);
  }

  private getDrilledItemName(args: IDrillEndEventArgs): string {
    const eventArgs = args as any;

    return (
      eventArgs?.groupName ??
      eventArgs?.item?.groupName ??
      eventArgs?.item?.name ??
      eventArgs?.name ??
      eventArgs?.renderItems?.[0]?.groupName ??
      eventArgs?.renderItems?.[0]?.name ??
      'Unknown Item'
    );
  }

  private getDrilledLevel(args: IDrillEndEventArgs): string {
    const eventArgs = args as any;

    const levelOrderName =
      eventArgs?.levelOrderName ??
      eventArgs?.item?.levelOrderName ??
      eventArgs?.renderItems?.[0]?.levelOrderName;

    if (typeof levelOrderName === 'string' && levelOrderName.trim()) {
      const parts = levelOrderName
        .split('#')
        .map((part: string) => part.trim())
        .filter(Boolean);

      return parts.length ? parts[parts.length - 1] : levelOrderName;
    }

    if (typeof eventArgs?.groupIndex === 'number') {
      return `Level ${eventArgs.groupIndex}`;
    }

    if (typeof eventArgs?.currentLevel === 'number') {
      return `Level ${eventArgs.currentLevel}`;
    }

    return 'Unknown Level';
  }
}

Best Practices

DO: Use Meaningful Header Formats

public levels = [
  {
    groupPath: 'Region',
    headerFormat: '${Region}'
  },
  {
    groupPath: 'Country',
    headerFormat: '${Country}'
  }
];

Use headers that clearly reflect the current hierarchy level.

DON'T: Use Unclear Headers

public levels = [
  {
    groupPath: 'Region',
    headerFormat: '${Data}'
  }
];

Avoid headers that reference unclear or unmapped fields.

DO: Include Aggregated Totals

If your data already includes aggregate values, surface them through the header format or tooltips.

public data = signal([
  { Region: 'North America', Country: 'USA', Value: 25460, RegionTotal: 27301 },
  { Region: 'North America', Country: 'Canada', Value: 1841, RegionTotal: 27301 }
]);

public levels = [
  {
    groupPath: 'Region',
    headerFormat: '${Region}'
  }
];

If you want totals visible in the header, make sure the field is available at the level where the header is rendered.

DO: Provide Visual Feedback

Use built-in breadcrumb support, meaningful headers, and optionally event handlers to update surrounding Angular UI when drilling starts or ends.

<ejs-treemap
  [enableDrillDown]="true"
  [enableBreadcrumb]="true"
  (drillStart)="onDrillStart($event)"
  (drillEnd)="onDrillEnd($event)">
</ejs-treemap>

DO: Limit Hierarchy Depth

Keep drill hierarchies manageable.

public levels = [
  { groupPath: 'Level1' },
  { groupPath: 'Level2' },
  { groupPath: 'Level3' }
];

Three or four levels are usually easier to navigate than very deep drill chains.

Troubleshooting

Issue: Drilldown is not working

Solution: Make sure enableDrillDown is enabled and each configured groupPath exists in the data source.

public levels = [
  { groupPath: 'Region' },
  { groupPath: 'Country' }
];

Issue: Breadcrumb is not showing

Solution: Enable both drilldown and breadcrumb.

[enableDrillDown]="true"
[enableBreadcrumb]="true"

Issue: Drill events are not firing

Solution: Use the documented drill event names.

(drillStart)="onDrillStart($event)"
(drillEnd)="onDrillEnd($event)"

Issue: Need a custom Back button

Solution: Prefer built-in breadcrumb for upward navigation. If you need an application button that returns to the root, recreate the TreeMap through Angular state rather than calling an undocumented instance method.