syncfusion-blazor-treemap

What this skill does

# Implementing TreeMap

**NuGet:** `Syncfusion.Blazor.TreeMap` + `Syncfusion.Blazor.Themes`  
**Namespace:** `Syncfusion.Blazor.TreeMap`

This skill collects all guidance for implementing the Syncfusion Blazor `TreeMap` component. Use the navigation guide below to open the specific reference topic you need; each reference file is self-contained and includes examples, edge cases, and troubleshooting.

## Official API Surface
- Component: `SfTreeMap<TValue>`
- Interface: `ITreeMap`
- Core child settings: `TreeMapLevels`, `TreeMapLeafItemSettings`, `TreeMapLegendSettings`, `TreeMapTooltipSettings`, `TreeMapSelectionSettings`, `TreeMapHighlightSettings`, `TreeMapEvents`
- Common enums: `LayoutMode`, `RenderingMode`, `LabelPosition`, `LabelPlacement`, `LabelIntersectAction`, `LegendMode`, `LegendPosition`, `LegendOrientation`, `LegendShape`, `SelectionMode`, `HighLightMode`
- Common event args: `LoadEventArgs`, `LoadedEventArgs`, `ItemRenderingEventArgs`, `ItemClickEventArgs`, `ItemSelectedEventArgs`, `ItemMoveEventArgs`, `LegendRenderingEventArgs`, `LegendItemRenderingEventArgs`, `TreeMapTooltipArgs`

## When to Use This Skill
- When integrating a hierarchical, area-proportional visualization in a Blazor app.
- When you need guidance on layouts, color-mapping, labels, legends, or drill-down.
- When configuring data-binding for hierarchical or flat datasets.
- When implementing accessibility, localization, print/export, or performance optimizations.

## ⚠️ Security Warning

**DO NOT bind TreeMap to untrusted public APIs or third-party data sources without proper validation.** Remote data can be manipulated to inject malicious code, corrupt visualizations, or cause denial-of-service attacks. Always:
- ✅ Use only internal, authenticated APIs you own and control
- ✅ Validate and sanitize ALL remote data before binding
- ✅ Implement server-side authorization and rate limiting
- ✅ Use HTTPS and verify SSL/TLS certificates
- ✅ HTML-encode string properties to prevent XSS

**For detailed security guidance, see:** [Security Considerations in data-binding.md](references/data-binding.md)

## Documentation and Navigation Guide

### API Reference
📄 **Read:** [references/api-reference.md](references/api-reference.md)
- Quick lookup for the main TreeMap component, child settings, events, methods, and enums.

### Getting Started
📄 **Read:** [references/getting-started.md](references/getting-started.md)
- Installation, NuGet package, project setup, minimal example.

### Data Binding and Sources
📄 **Read:** [references/data-binding.md](references/data-binding.md)
- Flat vs hierarchical data, local/remote sources, data adaptors.
- Remote data binding: Only to internal, authenticated APIs you control — do NOT bind directly to untrusted third-party endpoints. See [references/data-binding.md](references/data-binding.md) for the mandatory security checklist and safe patterns (server-side proxying, validation, sanitization, rate limits).

### Layout and Levels
📄 **Read:** [references/layout-and-levels.md](references/layout-and-levels.md)
- Layout algorithms, level grouping, headers and gaps.

### Leaf Items
📄 **Read:** [references/leaf-items.md](references/leaf-items.md)
- Leaf node styling, templates and label positioning.

### Color Mapping
📄 **Read:** [references/color-mapping.md](references/color-mapping.md)
- Range, equal, desaturation, palette mappings and strategies.

### Labels
📄 **Read:** [references/labels.md](references/labels.md)
- Data label templates, formatting and overflow handling.

### Legend
📄 **Read:** [references/legend.md](references/legend.md)
- Legend modes, positioning and smart legend behaviors.

### Tooltips
📄 **Read:** [references/tooltip.md](references/tooltip.md)
- Default and templated tooltips, styling and dynamic content.

### Drill-Down
📄 **Read:** [references/drill-down.md](references/drill-down.md)
- Enabling drill-down, breadcrumbs, and custom navigation.

### Selection & Highlight
📄 **Read:** [references/selection-and-highlight.md](references/selection-and-highlight.md)
- Selection modes, highlight, and programmatic selection.

### Events & Methods
📄 **Read:** [references/events-and-methods.md](references/events-and-methods.md)
- Lifecycle events, render events, print/export methods.

### Advanced Features
📄 **Read:** [references/advanced-features.md](references/advanced-features.md)
- Accessibility, localization, performance, placing the TreeMap inside other components.

### Troubleshooting
📄 **Read:** [references/troubleshooting.md](references/troubleshooting.md)
- Common issues, rendering and data-binding fixes.

## Quick Start (Minimal example)

```csharp
@using Syncfusion.Blazor.TreeMap

<SfTreeMap DataSource="@Data"> 
  <TreeMapLevels>
    <TreeMapLevel GroupPath="Category" />
  </TreeMapLevels>
</SfTreeMap>

@code {
  public object[] Data = new[] { new { Category = "A", Value = 10 } };
}
```

## Common Patterns
- Quick selection + drill-down for hierarchical exploration.
- Use `RangeColorMapping` for value-driven coloring and `Palette` when mapping explicit colors.
- Prefer server-side paging/aggregation for very large datasets and use client-side rendering for moderate datasets.

## References
- All reference files are in `references/` and are self-contained with TOCs.

---

# Implementing Syncfusion Blazor TreeMap

A comprehensive guide for implementing hierarchical data visualization using Syncfusion Blazor TreeMap component. TreeMaps display hierarchical data as nested rectangles where the size and color of each rectangle represents different data dimensions.

## When to Use This Skill

Use this skill when you need to:

- **Visualize hierarchical data structures** - Display organizational charts, file systems, or nested data with parent-child relationships
- **Show proportional data** - Represent data where rectangle size reflects quantitative values (sales, population, disk space)
- **Enable drill-down navigation** - Allow users to interactively explore multi-level hierarchical data
- **Compare data distributions** - Use color mapping to show additional dimensions (growth, performance, categories)
- **Display large datasets** - Efficiently visualize hundreds or thousands of data points in limited space
- **Create interactive dashboards** - Combine with selection, highlighting, tooltips, and legends for rich user experience

**Common Use Cases:**
- Portfolio analysis and asset allocation
- Market share and competitive analysis
- Budget and resource distribution
- File/folder size visualization
- Organizational structure displays
- Product category sales analysis
- Website analytics (page hierarchy and traffic)

## Component Overview

The TreeMap component organizes data into nested rectangles using various layout algorithms (Squarified, SliceDiceAuto, Horizontal, Vertical). Each rectangle's size is proportional to a specified data value, and colors can represent additional dimensions through sophisticated color mapping strategies.

**Key Capabilities:**
- Multiple layout algorithms for optimal space utilization
- Hierarchical data binding (flat or nested structures)
- Multi-level drill-down with breadcrumb navigation
- Advanced color mapping (range, equal, desaturation, palette)
- Interactive legends with filtering
- Rich tooltips with templates
- Selection and highlight modes
- Print and export (PDF, PNG, JPEG, SVG)
- Full accessibility support (ARIA, keyboard navigation)

## Documentation and Navigation Guide

### Getting Started
📄 **Read:** [references/getting-started.md](references/getting-started.md)

**When to read:** Setting up TreeMap for the first time, installation, basic implementation

**What's covered:**
- Installation via Visual Studio, VS Code, or .NET CLI
- NuGet package setup (Syncfusion.Blazor.TreeMap)
- Service registration and namespace imports
- CSS theme configuration
- Basic TreeMap implementation with sample data
- License registration for production
- Blazor WebAssembly vs Web App differ