# Usage

The treemap chart provides a method for displaying hierarchical data using nested rectangles.

Treemaps display hierarchical (tree-structured) data as a set of nested rectangles. Each branch of the tree is given a rectangle, which is then tiled with smaller rectangles representing sub-branches. A leaf node's rectangle has an area proportional to a specified dimension of the data.

const config = {
  type: 'treemap',
  data: {
    datasets: [
      {
        label: 'My treemap dataset',
        tree: [15, 6, 6, 5, 4, 3, 2, 2],
        borderColor: 'green',
        borderWidth: 1,
        spacing: 0,
        backgroundColor: (ctx) => colorFromRaw(ctx),
      }
    ],
  },
  options: {
    plugins: {
      title: {
        display: true,
        text: 'My treemap chart'
      },
      legend: {
        display: false
      }
    }
  }
};const config = {
  type: 'treemap',
  data: {
    datasets: [
      {
        label: 'My treemap dataset',
        tree: [15, 6, 6, 5, 4, 3, 2, 2],
        borderColor: 'green',
        borderWidth: 1,
        spacing: 0,
        backgroundColor: (ctx) => colorFromRaw(ctx),
      }
    ],
  },
  options: {
    plugins: {
      title: {
        display: true,
        text: 'My treemap chart'
      },
      legend: {
        display: false
      }
    }
  }
};

# Dataset Options

Namespaces:

data.datasets[index] - options for this dataset only
options.datasets.treemap - options for all treemap datasets
options.elements.treemap - options for all treemap elements
options - options for the whole chart

The treemap chart allows a number of properties to be specified for each dataset. These are used to set display properties for a specific dataset.

Name	Type	Scriptable (opens new window)	Default
`backgroundColor`	`Color` (opens new window)	Yes	`undefined`
`borderColor`	`Color` (opens new window)	Yes	`undefined`
`borderRadius`	`number` \| `object`	Yes	`0`
`borderWidth`	`number`\|`object`	-	`0`
`captions`	`object`	-
`dividers`	`object`	-
`groups`	`string[]`	-	`undefined`
`hoverBackgroundColor`	`Color` (opens new window)	Yes	`undefined`
`hoverBorderColor`	`Color` (opens new window)	Yes	`undefined`
`hoverBorderWidth`	`number`	Yes	`undefined`
`key`	`string`	-	`undefined`
`label`	`string`	-	`undefined`
`labels`	`object`	-
`rtl`	`boolean`	-	`false`
`spacing`	`number`	-	`0.5`
`sumKeys`	`string[]`	-	`undefined`
`tree`	`number[]` \| `object[]` \| `object`	-	required
`treeLeafKey`	`string`	-	`_leaf`

All these values, if undefined, fallback to the scopes described in option resolution (opens new window).

# General

Name	Description
`groups`	Define how to display multiple levels of hierarchy. Data is summarized to groups internally.
`key`	Define the key name in data objects to use for value.
`label`	The label for the dataset which appears in the legend and tooltips.
`rtl`	If `true`, the treemap elements are rendering from right to left.
`sumKeys`	Define multiple keys to add additional sums, on top of the `key` one, for scriptable options use.
`tree`	Tree data should be provided in `tree` property of dataset. `data` is then automatically build.
`treeLeafKey`	The name of the key where the object key of leaf node of tree object is stored. Used only when `tree` is an `object`, as hierarchical data.

Only the tree, treeLeafKey, key, sumKeys and groups options need to be specified in the dataset namespace.

function colorFromRaw(ctx) {
  if (ctx.type !== 'data') {
    return 'transparent';
  }
  const value = ctx.raw.v;
  let alpha = (1 + Math.log(value)) / 5;
  const color = 'green';
  return helpers.color(color)
    .alpha(alpha)
    .rgbString();
}
const data = [
  {category: 'main', value: 1},
  {category: 'main', value: 2},
  {category: 'main', value: 3},
  {category: 'other', value: 4},
  {category: 'other', value: 5},
];
const config = {
  type: 'treemap',
  data: {
    datasets: [{
      tree: data,
      key: 'value',
      groups: ['category'],
      backgroundColor: (ctx) => colorFromRaw(ctx),
    }]
  },
};

# Styling

The style of the treemap element can be controlled with the following properties:

Name	Description
`backgroundColor`	The treemap element background color.
`borderColor`	The treemap element border color.
`borderRadius`	Radius of the rectangle of treemap element (in pixels).
`borderWidth`	The treemap element border width (in pixels).
`spacing`	Fixed distance (in pixels) between all treemap elements.

If the value is undefined, fallbacks to the associated elements.treemap.* options.

# borderRadius

If this value is a number, it is applied to all corners of the rectangle (topLeft, topRight, bottomLeft, bottomRight). If this value is an object, the topLeft property defines the top-left corners border radius. Similarly, the topRight, bottomLeft, and bottomRight properties can also be specified. Omitted corners have radius of 0.

# Interactions

The interaction with each element can be controlled with the following properties:

Name	Description
`hoverBackgroundColor`	The treemap element background color when hovered.
`hoverBorderColor`	The treemap element border color when hovered.
`hoverBorderWidth`	The treemap element border width (in pixels) when hovered.

If the value is undefined, fallbacks to the associated elements.treemap.* options.

# Labels

Namespaces:

data.datasets[index].labels - options for this dataset only
options.datasets.treemap.labels - options for all treemap datasets
options.elements.treemap.labels - options for all treemap elements
options - options for the whole chart

The labels options can control if and how a label, to represent the data, can be shown in the rectangle, with the following properties:

Name	Type	Scriptable (opens new window)	Default
`align`	`string`	Yes	`center`
`color`	`Color` \| `Color[]`	Yes	`'black'`
`display`	`boolean`	-	`false`
`formatter`	`function`	Yes
`font`	`Font` \| `Font[]`	Yes	`{}`
`hoverColor`	`Color` \| `Color[]`	Yes	`undefined`
`hoverFont`	`Font` \| `Font[]`	Yes	`{}`
`overflow`	`string`	Yes	`cut`
`padding`	`number`	-	`3`
`position`	`string`	Yes	`middle`

All these values, if undefined, fallback to the scopes described in option resolution (opens new window).

WARNING

Labels only apply if display is true.

# Align

The align property specifies the text horizontal alignment used when drawing the label. The possible values are:

center: the text is centered. It is the default.
left: the text is left-aligned.
right: the text is right-aligned.

# Overflow

The overflow property controls what happens to a label that is too big to fit into a rectangle. The possible values are:

cut: if the label is too big, it will be cut to stay inside the rectangle. It is the default.
hidden: the label is removed altogether if the rectangle is too small for it.
fit: the label will be automatically fit inside the rectangle if its dimension is bigger than the rectangle size.

# Position

The position property specifies the text vertical alignment used when drawing the label. The possible values are:

middle: the text is in the middle of the rectangle. It is the default.
top: the text is in the top of the rectangle.
bottom: the text is in the bottom of the rectangle.

# Formatter

Data values are converted to string. If values are grouped, the value of the group and the value (as string) are shown.

This default behavior can be overridden by the formatter which is a scriptable (opens new window) option.

A formatter can return a string (for a single line) or an array of strings (for multiple lines, where each item represents a new line).

In the following example, every label of the treemap would be displayed with the unit.

const config = {
  type: 'treemap',
  data: {
    datasets: [{
      tree: [15, 6, 6, 5, 4, 3, 2, 2],
      labels: {
        display: false,
        formatter: (ctx) => 'Kmq ' + ctx.raw.v
      }
    }]
  },
};

# Fonts and colors

When the label to draw has multiple lines, you can use different font and color for each row of the label. This is enabled configuring an array of fonts or colors for those options. When the lines are more than the configured fonts of colors, the last configuration of those options is used for all remaining lines.

See on Chart.js documentation more details about font (opens new window) and color (opens new window) options.

# Captions

Namespaces:

data.datasets[index].captions - options for this dataset only
options.datasets.treemap.captions - options for all treemap datasets
options.elements.treemap.captions - options for all treemap elements
options - options for the whole chart

The captions options can control if and how a captions, to represent the group of the chart, can be shown in the rectangle, with the following properties:

Name	Type	Scriptable (opens new window)	Default
`align`	`string`	Yes	`undefined` but `left` is used because default `rtl` option is `false`.
`color`	`Color` (opens new window)	Yes	`'black'`
`display`	`boolean`	-	`true`
`font` (opens new window)	`Font`	Yes	`{}`
`formatter`	`function`	Yes
`hoverColor`	`Color` (opens new window)	Yes	`undefined`
`hoverFont` (opens new window)	`Font`	Yes	`{}`
`padding`	`number`	-	`3`

All these values, if undefined, fallback to the scopes described in option resolution (opens new window).

# Caption Align

The align property specifies the text horizontal alignment used when drawing the caption. The possible values are:

left: the text is left-aligned.
center: the text is centered.
right: the text is right-aligned.

If undefined, right is used if rtl option is set to true, otherwise left.

# Caption Formatter

If values are grouped, the value of the group is shown in the chart as caption for all elements belonging to the group.

This default behavior can be overridden by the formatter which is a scriptable (opens new window) option.

A formatter can return a string.

In the following example, every caption of the treemap would be displayed with an additional label.

const data = [
  {category: 'main', subcategory: 'one', value: 1},
  {category: 'main', subcategory: 'one', value: 5},
  {category: 'main', subcategory: 'one', value: 3},
  {category: 'main', subcategory: 'two', value: 2},
  {category: 'main', subcategory: 'two', value: 1},
  {category: 'main', subcategory: 'two', value: 8},
  {category: 'other', subcategory: 'one', value: 4},
  {category: 'other', subcategory: 'one', value: 5},
  {category: 'other', subcategory: 'two', value: 4},
  {category: 'other', subcategory: 'two', value: 1},
];
const config = {
  type: 'treemap',
  data: {
    datasets: [{
      tree: data,
      key: 'value',
      groups: ['category', 'subcategory', 'value'],
      captions: {
        display: true,
        formatter(ctx) {
          return ctx.type === 'data' ? 'G: ' + ctx.raw.g : '';
        }
      },
    }]
  },
};

# Dividers

Namespaces:

data.datasets[index].dividers - options for this dataset only
options.datasets.treemap.dividers - options for all treemap datasets
options.elements.treemap.dividers - options for all treemap elements
options - options for the whole chart

The divider is a line which splits a treemap elements in grouped elements and can be controlled with the following properties:

Name	Type	Scriptable (opens new window)	Default
`display`	`boolean`	-	`false`
`lineCapStyle`	`string`	-	`'butt'`
`lineColor`	`Color` (opens new window)	-	`'black'`
`lineDash`	`number[]`	-	`[]`
`lineDashOffset`	`number`	-	`0`
`lineWidth`	`number`	-	`1`

All these values, if undefined, fallback to the scopes described in option resolution (opens new window).

# Line Styling

The style of the divider line can be controlled with the following properties:

Name	Description
`display`	If `true`, the dividers will be applied to the grouped treemap elements, only if grouping.
`lineCapStyle`	Cap style of the divider line. See MDN (opens new window).
`lineColor`	Color of the divider line.
`lineDash`	Length and spacing of divider dashes. See MDN (opens new window).
`lineDashOffset`	Offset for divider line dashes. See MDN (opens new window).
`lineWidth`	Divider line width (in pixels).

If the value is undefined, fallbacks to the associated elements.treemap.dividers.* options.

← Integration