Mermaid supports Treemap Diagrams now!!!

3 July 2025 • 4 mins

Mermaid continues to expand its toolkit with the introduction of Treemap diagrams! This new diagram type (currently in beta) brings powerful hierarchical data visualization capabilities to the Mermaid. Treemaps offer an intuitive way to represent complex hierarchical relationships.
Learn more here.

What Are Treemap Diagrams?

Treemap diagrams display hierarchical data as a set of nested rectangles. Each branch of your data tree becomes a rectangle, which is then tiled with smaller rectangles representing sub-branches. The magic lies in the proportional sizing – each rectangle’s area corresponds to its value, making it instantly clear which categories dominate your dataset.

It is like as a bird’s-eye view of your data hierarchy where size matters. Unlike traditional tree diagrams that focus on connections, treemaps emphasize proportions and space efficiency.

Treemaps excel in several scenarios:

• Space Efficiency: Pack large amounts of hierarchical data into a compact visualization
• Proportion Comparison: Instantly see which categories are largest at a glance
• Pattern Recognition: Spot outliers and trends in your hierarchical data
• Multi-level Analysis: Navigate through different levels of detail seamlessly

Getting Started with Mermaid Treemaps

The syntax is refreshingly simple. Here’s a basic example:

treemap-beta
"Category A"
  "Item A1": 10
  "Item A2": 20
"Category B"
  "Item B1": 15
  "Item B2": 25

The structure follows these rules:

• Parent nodes are defined with quoted text: "Section Name"
• Leaf nodes include values: "Leaf Name": value
• Hierarchy is created through indentation
• Styling can be applied using the :::class syntax

Real-World Example: Company Budget Visualization

Let’s visualize a company’s budget allocation:

treemap-beta
"Annual Budget"
  "Operations"
    "Salaries": 700000
    "Equipment": 200000
    "Supplies": 100000
  "Marketing"
    "Advertising": 400000
    "Events": 100000
  "R&D"
    "Research": 300000
    "Development": 250000

This immediately shows that Operations (especially Salaries) takes up the largest portion of the budget, while Marketing and R&D have smaller, more balanced allocations.

Advanced Features

Custom Styling

Make important categories stand out with custom styling:

treemap-beta
"Main"
    "A": 20
    "B":::important
        "B1": 10
        "B2": 15
    "C": 5

classDef important fill:#f96,stroke:#333,stroke-width:2px;

Value Formatting

Display values in meaningful formats using the valueFormat configuration:

---
config:
  treemap:
    valueFormat: '$0,0'
---

This transforms raw numbers like 700000 into formatted values like $700,000.

You can also use:

• $.2f for currency with decimals
• .1% for percentages
• , for thousands separators

Theme Customization

Apply different themes to match your design aesthetic:

---
config:
    theme: 'forest'
---

Configuration Options

Treemaps offer extensive customization:

Option	Description	Default
padding	Space between nodes	10
diagramPadding	Padding around entire diagram	8
showValues	Display values in rectangles	true
valueFontSize	Font size for values	12
labelFontSize	Font size for labels	14
valueFormat	Number formatting pattern	‘,’

Common Use Cases

1. Disk Space Analysis

Visualize which folders consume the most storage space on your system.

2. Market Share Visualization

Show how different companies or products divide up a market.

3. Organizational Headcount

Display department sizes and team structures proportionally.

4. Portfolio Composition

Illustrate investment allocations across different asset classes.

5. Website Analytics

Show traffic distribution across different pages and sections.

Best Practices

1. Keep It Shallow: Treemaps work best with 2-3 levels of hierarchy
2. Mind the Minimums: Very small values may be hard to see or label
3. Use Color Wisely: Apply styling to highlight important categories
4. Format Values: Use appropriate formatting for your data type
5. Consider Alternatives: For negative values or flow data, consider other diagram types

What’s Next?

As a beta feature, the treemap syntax may evolve based on community feedback. The Mermaid team welcomes input through our GitHub repository. Future enhancements might include:

• Interactive features
• Animation support
• More layout algorithms
• Enhanced labeling options

Conclusion

Mermaid’s new Treemap diagrams fill an important gap in hierarchical data visualization. With their intuitive syntax and powerful customization options, they make it easy to create professional-looking visualizations that clearly communicate proportions and hierarchies.

Start experimenting with treemaps in your Mermaid diagrams today – your hierarchical data will thank you for the clarity!

---