Treemap Charts

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.

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:

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

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

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'
      }
    }
  }
});

Customize Leaf Node Labels

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

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

Complete Example

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.

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:

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

Complete Example

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'
      }
    }
  }
});

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.