Implementing Windows Forms TreeMap

Guide for implementing the Syncfusion® Windows Forms TreeMap control for visualizing hierarchical data through nested, color-coded rectangles. TreeMaps efficiently display large datasets where the size and color of rectangles represent quantitative values.

When to Use This Skill

Use this skill when you need to:

Visualize hierarchical data with nested rectangles
Display large datasets in space-efficient layouts
Show proportional relationships through rectangle sizes
Color-code data values with multiple mapping strategies
Implement TreeMap layouts (Squarified, SliceAndDice variations)
Create interactive visualizations with tooltips and legends
Customize TreeMap appearance with headers, labels, and custom rendering
Analyze categorical data like stock portfolios, disk usage, or sales by region

TreeMap Overview

Tree maps are ideal for visualizing large amounts of data where space is split into rectangles sized and colored based on quantitative variables. The levels in the hierarchy are visualized as rectangles containing other rectangles.

Key concepts:

Rectangles represent data items - Size based on weight value
Hierarchical nesting - Parent rectangles contain child rectangles
Color coding - Colors represent data categories or value ranges
Space efficiency - Entire visualization area is utilized
Multiple levels - Support for multi-level hierarchies

Common Use Cases

TreeMaps are used to represent large or complex data sets in various applications:

Stock Market Analysis - Rectangle size represents stock weight in index, color shows gain/loss range
Internet Usage Categories - Visualize usage across retail, social networks, search, etc.
News Aggregation - Colors represent sections (business, politics), size represents story frequency
Weather Analysis - Opacity represents humidity, size represents geographic area
Disk Space Usage - Visualize file and folder sizes in storage
Sales by Region/Product - Show sales distribution across categories
Portfolio Management - Display asset allocation and performance

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Assembly deployment and control dependencies
NuGet package installation
Creating TreeMap control instance
Adding control to Windows Forms application
Basic namespace and assembly references
First working TreeMap example

Overview and Visualization Concepts

📄 Read: references/overview-and-use-cases.md

What TreeMaps are and how they work
Hierarchical information visualization
Clustered rectangles and data representation
Real-world use case scenarios
When to choose TreeMap over other visualizations

Core Configuration - Weight and Color Paths

📄 Read: references/weight-and-color-paths.md

WeightValuePath property for sizing rectangles
ColorValuePath property for color mapping
Data binding path requirements
Field specifications in data models
Configuration examples

Data Binding and Levels

📄 Read: references/items-source-and-levels.md

ItemsSource setup with flat data collections
Creating data view models
TreeMapFlatLevel configuration
GroupPath for hierarchical grouping
GroupGap for visual separation
Multi-level TreeMap structure
Complete data binding examples

Layout Modes

📄 Read: references/layout-modes.md

ItemsLayoutMode property overview
Squarified layout algorithm
SliceAndDiceAuto layout
SliceAndDiceHorizontal layout
SliceAndDiceVertical layout
Choosing the right layout for your data
Visual comparisons

Color Mapping Strategies

📄 Read: references/color-mapping.md

Four color mapping types overview
UniColorMapping for single color application
RangeBrushColorMapping for value ranges
DesaturationColorMapping for opacity-based coloring
PaletteColorMapping for color collections
LeafColorMapping configuration
Complete examples for each type

Headers and Labels Customization

📄 Read: references/headers-and-labels.md

Label font and color customization
LabelBrush and LabelBackgroundBrush
Label border properties
HeaderBrush configuration
ShowLabels property for visibility
HeaderHeight for level headers
Complete styling examples

Legend Support

📄 Read: references/legend-support.md

TreeMap legend for color value demonstration
LegendPosition configuration (Left, Right, Top, Bottom)
LegendType for icon shapes
LegendGap for spacing
Integration with RangeBrushColorMapping
LegendLabel in RangeBrush items

Tooltips and Advanced Customization

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

Tooltip visibility and configuration
HeaderToolTipInfo for group tooltips
ItemToolTipInfo for leaf tooltips
Custom tooltip content patterns
LeafItemDrawing event for custom rendering
Advanced leaf node customization
Custom graphics and images in TreeMap

Quick Start Example

Step 1: Install NuGet Package

Install-Package Syncfusion.TreeMap.WinForms

Step 2: Create Data Model

using System.Collections.ObjectModel;

public class PopulationDetail
{
    public string Continent { get; set; }
    public string Country { get; set; }
    public double Growth { get; set; }
    public double Population { get; set; }
}

public class PopulationViewModel
{
    public ObservableCollection<PopulationDetail> PopulationDetails { get; set; }
    
    public PopulationViewModel()
    {
        PopulationDetails = new ObservableCollection<PopulationDetail>();
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "Asia", 
            Country = "Indonesia", 
            Growth = 3, 
            Population = 237641326 
        });
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "Asia", 
            Country = "Russia", 
            Growth = 2, 
            Population = 152518015 
        });
        
        PopulationDetails.Add(new PopulationDetail 
        { 
            Continent = "North America", 
            Country = "United States", 
            Growth = 4, 
            Population = 315645000 
        });
        
        // Add more data...
    }
}

Step 3: Configure TreeMap

using Syncfusion.Windows.Forms.TreeMap;

public class MyForm : Form
{
    private TreeMap treeMap;
    
    public MyForm()
    {
        InitializeComponent();
        
        // Create TreeMap instance
        treeMap = new TreeMap();
        
        // Set data source
        PopulationViewModel data = new PopulationViewModel();
        treeMap.ItemsSource = data.PopulationDetails;
        
        // Configure paths
        treeMap.WeightValuePath = "Population";
        treeMap.ColorValuePath = "Growth";
        
        // Set layout mode
        treeMap.ItemsLayoutMode = ItemsLayoutModes.Squarified;
        
        // Add first level (Continent)
        TreeMapFlatLevel level1 = new TreeMapFlatLevel();
        level1.GroupPath = "Continent";
        level1.ShowLabels = true;
        treeMap.Levels.Add(level1);
        
        // Add second level (Country)
        TreeMapFlatLevel level2 = new TreeMapFlatLevel();
        level2.GroupPath = "Country";
        level2.ShowLabels = true;
        level2.HeaderHeight = 25;
        treeMap.Levels.Add(level2);
        
        // Add color mapping
        UniColorMapping colorMapping = new UniColorMapping();
        colorMapping.Color = Color.MediumSlateBlue;
        treeMap.LeafColorMapping = colorMapping;
        
        // Set size and add to form
        treeMap.Size = new Size(800, 600);
        treeMap.Location = new Point(10, 10);
        this.Controls.Add(treeMap);
    }
}

Common Patterns

Multi-Level Hierarchy Pattern

// Create levels for nested grouping
TreeMapFlatLevel level1 = new TreeMapFlatLevel();
level1.GroupPath = "Category";
level1.ShowLabels = true;
treeMap.Levels.Add(level1);

TreeMapFlatLevel level2 = new TreeMapFlatLevel();
level2.GroupPath = "SubCategory";
level2.ShowLabels = true;
level2.HeaderHeight = 25;
treeMap.Levels.Add(level2);

TreeMapFlatLevel level3 = new TreeMapFlatLevel();
level3.GroupPath = "Item";
level3.ShowLabels = true;
level3.HeaderHeight = 20;
treeMap.Levels.Add(level3);

Range-Based Color Mapping Pattern

RangeBrushColorMapping rangeMapping = new RangeBrushColorMapping();

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#77D8D8"), 
    From = 0, 
    To = 1, 
    LegendLabel = "Low" 
});

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#FFAF51"), 
    From = 1, 
    To = 5, 
    LegendLabel = "Medium" 
});

rangeMapping.Brushes.Add(new RangeBrush 
{ 
    Color = ColorTranslator.FromHtml("#F3D240"), 
    From = 5, 
    To = 20, 
    LegendLabel = "High" 
});

treeMap.LeafColorMapping = rangeMapping;

Interactive Tooltip Pattern

// Enable tooltips
treeMap.IsToolTipVisible = true;

// Configure header tooltip
ToolTipInfo headerToolTip = new ToolTipInfo();
headerToolTip.ToolTipHeaderPattern = "<b>{Label}</b>";
headerToolTip.ToolTipContentPattern = "Growth: {Growth}%";
treeMap.HeaderToolTipInfo = headerToolTip;

// Configure item tooltip
ToolTipInfo itemToolTip = new ToolTipInfo();
itemToolTip.ToolTipHeaderPattern = "<b>{Country}</b>";
itemToolTip.ToolTipContentPattern = "Growth: {Growth}%\nPopulation: {Population}";
treeMap.ItemToolTipInfo = itemToolTip;

Key Properties Reference

Essential Properties

Property	Type	Description
`ItemsSource`	object	Data collection to visualize
`WeightValuePath`	string	Path to field determining rectangle size
`ColorValuePath`	string	Path to field for color mapping
`ItemsLayoutMode`	ItemsLayoutModes	Layout algorithm selection
`Levels`	TreeMapLevelCollection	Collection of hierarchical levels
`LeafColorMapping`	TreeMapColorMapping	Color mapping strategy

Customization Properties

Property	Type	Description
`LabelFont`	Font	Font for leaf node labels
`LabelBrush`	Brush	Label text color
`LabelBackgroundBrush`	Brush	Label background color
`LabelBorderBrush`	Brush	Label border color
`LabelBorderThickness`	int	Label border width
`HeaderBrush`	Brush	Header background color

Legend Properties

Property	Type	Description
`LegendPosition`	LegendPositions	Legend placement (Top/Bottom/Left/Right)
`LegendType`	LegendTypes	Legend icon shape
`LegendGap`	int	Spacing between legend items

Tooltip Properties

Property	Type	Description
`IsToolTipVisible`	bool	Enable/disable tooltips
`HeaderToolTipInfo`	ToolTipInfo	Tooltip configuration for headers
`ItemToolTipInfo`	ToolTipInfo	Tooltip configuration for leaf items

Decision Guide

When to Use Each Layout Mode

Squarified:

Best for balanced aspect ratios
More readable rectangles
General-purpose visualization
Use when: Data proportions vary widely

SliceAndDiceAuto:

Alternates horizontal/vertical splits by level
Good for hierarchical clarity
Use when: Showing clear level separation

SliceAndDiceHorizontal:

All rectangles split horizontally
Use when: Wide display area available

SliceAndDiceVertical:

All rectangles split vertically
Use when: Tall display area available

Choosing Color Mapping

UniColorMapping:

Single color for all items
Use when: Color doesn't represent data, only grouping

RangeBrushColorMapping:

Different colors for value ranges
Use when: Categorizing data into discrete ranges (low/medium/high)

DesaturationColorMapping:

Single base color with varying opacity
Use when: Showing continuous gradient of values

PaletteColorMapping:

Cycle through color collection
Use when: Distinguishing categories without value meaning

Edge Cases and Troubleshooting

Missing Data in Visualization

Cause: WeightValuePath or ColorValuePath field missing in data model
Solution: Ensure all data objects have required properties

Labels Not Showing

Cause: ShowLabels property not set on TreeMapFlatLevel
Solution: Set level.ShowLabels = true for each level

Colors Not Applying

Cause: LeafColorMapping not configured
Solution: Create and assign color mapping to TreeMap.LeafColorMapping

Assembly Reference Error

Cause: Missing Syncfusion.TreeMap.Windows assembly
Solution: Install Syncfusion.TreeMap.WinForms NuGet package

Levels Not Grouping Correctly

Cause: GroupPath doesn't match data property name
Solution: Verify GroupPath string matches exact property name (case-sensitive)

Best Practices

Use ObservableCollection for dynamic data that may change
Set appropriate HeaderHeight for multi-level TreeMaps (20-30 pixels)
Choose color mapping based on data meaning (ranges vs. gradient)
Enable tooltips for interactive exploration of data
Use GroupGap to visually separate levels (5-10 pixels)
Test with realistic data sizes to ensure layout works well
Provide legends when using RangeBrushColorMapping
Consider layout mode based on display dimensions

Assembly: Syncfusion.TreeMap.Windows
Namespace: Syncfusion.Windows.Forms.TreeMap
NuGet Package: Syncfusion.TreeMap.WinForms

syncfusion-winforms-treemap