# Treemap Charts

## Content

A treemap chart visualizes hierarchical data using nested rectangles.

* Each rectangle represents a node in the hierarchy.
* The size of each rectangle is determined by a numeric value.
* The hierarchy is defined by multiple fields in the `details` encoding.

Treemaps are useful for comparing proportions across hierarchical categories in a compact layout.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260401.ffc763.png?width=600)

## Data Structure Requirements

A treemap chart requires:

* A numeric field in `values` to determine rectangle size.
* One or more categorical fields in `details` to define hierarchy levels.

When multiple fields are specified in `details`, they form a hierarchy in the given order:

```javascript
details: [
  { field: 'Category' },
  { field: 'Subcategory' },
  { field: 'Product' }
]
```

* `Category` → top-level groups
* `Subcategory` → nested within Category
* `Product` → leaf nodes

By default, only leaf nodes are rendered as visible rectangles.

## Example Data

```javascript
const dataManager = spread.dataManager();

function createTreemapTable(dataManager) {
    const records = [
        ['Beverages', 'Juice', 'Apple Juice', 420],
        ['Beverages', 'Juice', 'Orange Juice', 680],
        ['Beverages', 'Dairy', 'Milk', 950],
        ['Snacks', 'Chocolate', 'Dark Chocolate', 530],
        ['Snacks', 'Chocolate', 'Milk Chocolate', 610],
        ['Snacks', 'Meat', 'Beef Jerky', 720],
        ['Snacks', 'Chips', 'Potato Chips', 480],
        ['Snacks', 'Chips', 'Corn Chips', 390],
    ];

    const columns = ['Category', 'Subcategory', 'Product', 'Sales'];

    return dataManager.addTable('TreemapData', {
        data: records.map((x) => {
            const record = {};
            columns.forEach((c, i) => record[c] = x[i]);
            return record;
        })
    });
}

const TreemapData = createTreemapTable(dataManager);
await TreemapData.fetch();
```

## Create a Treemap Chart

```javascript
const sheet = spread.getActiveSheet();
sheet.name("Treemap Chart");

const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 600, 400);

dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260401.826fef.png?width=600)

## Customize Leaf Node Labels

You can display text inside leaf nodes using the `text` configuration in the plot.

```javascript
config: {
  text: [{
    template: '{detailFields.value}',
  }]
}
```

**Complete Example**

```javascript
dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      },
      config: {
        text: [
          {
            template: '{detailFields.value}'
          }
        ]
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

This configuration applies to leaf nodes only.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260401.3c06da.png?width=600)
The `template` property uses the same template mechanism as other Data Chart labels.

## Display Non-Leaf Nodes with Headers

When multiple levels are defined in `details`, you can enable treemap headers to display non-leaf nodes.
Unlike `text`, which applies to leaf nodes, treemap headers are rendered for non-leaf nodes.

### Enable Treemap Header

Configure the `header` option inside `treemap` in the plot configuration:

```javascript
config: {
  treemap: {
    header: {
      template: '{detailFields.value}',
    textStyle: {
      fontSize: 14,
      fontWeight: 'Bold'
    }
    }
  }
}
```

**Complete Example**

```auto
dataChart.setChartConfig({
  tableName: 'TreemapData',
  plots: [
    {
      type: GC.Spread.Sheets.DataCharts.DataChartType.treemap,
      encodings: {
        values: [
          {
            field: 'Sales',
            aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
          }
        ],
        details: [
          { field: 'Category' },
          { field: 'Subcategory' },
          { field: 'Product' }
        ]
      },
      config: {
        text: [
          {
            template: '{detailFields.value}'
          }
        ],
        treemap: {
          header: {
            template: '{detailFields.value}',
            textStyle: {
              fontSize: 14,
              fontWeight: 'Bold'
            }
          }
        }
      }
    }
  ],
  config: {
    header: {
      title: "Treemap Chart",
      textStyle: {
        fontSize: 18,
        fontWeight: 'Bold'
      }
    }
  }
});
```

![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260401.33378b.png?width=600)
If `template` is not specified or is an empty string, the header is not displayed.

### Header Behavior

* The header occupies space within the node.
* The subtree is laid out in the remaining area.
* The header size automatically adjusts to fit its content.
* If the header size exceeds its parent rectangle, the header is not displayed.

## Limitations

* Hover animation is not supported.
* The `alignment` and `overflow` properties in `textStyle` do not take effect for treemap headers.
* Newline characters are not supported in treemap header text.