Skip to content

Migrating to v5

v5 is the release where the options that were never quite right get fixed. The changes are grouped by what you have to look for in your own configuration.

Chart.js 3 users stay on chartjs-chart-treemap@4; nothing here is backported.

Change v4 v5
Chart.js version 3.8 or newer 4.0 or newer
Input data tree: [...], plus data: [] for TypeScript data: [...]
Rebuild after an in-place edit bump treeVersion just chart.update()
Leaf key for nested objects treeLeafKey leafKey
Reading a rectangle dataset.data[i] ctx.raw, item.parsed, controller.getParsed(i)
Datalabels formatter (value) => value.v (_, ctx) => ctx.chart.getDatasetMeta(ctx.datasetIndex).controller.getParsed(ctx.dataIndex).v
rtl, spacing, unsorted, displayMode options.elements.treemap or the dataset options.datasets.treemap or the dataset
dividers an option removed; use a scriptable borderWidth
Text clipping at the border at the padding; set padding: 0 for the v4 look

The peer dependency is now >=4.0.0 and registering against an older Chart.js throws with a message naming the version.

Chart.js 3 exposed chart.js/helpers through an exports map that Webpack 5 does not accept, which is why bundling could fail to resolve that subpath. Upgrading Chart.js is the fix.

datasets: [{
tree: rows,
data: [], // TypeScript only
data: rows,
key: 'value',
}]

data accepts exactly what tree accepted: numbers, objects, or a nested object addressed through leafKey. A dataset that still has tree throws at the first update rather than drawing an empty chart.

treeVersion is gone. Edit data in place and call chart.update().

treeLeafKey is now leafKey, since there is no longer a tree for it to refer to.

The controller no longer writes the computed rectangles back into the dataset. dataset.data stays exactly as you passed it, and the rectangles are the parsed data - one node per rectangle, and a grouped treemap has more rectangles than you supplied rows.

To read a node Use
in a scriptable option ctx.raw, unchanged from v4
in a tooltip callback item.parsed
anywhere else chart.getDatasetMeta(i).controller.getParsed(index)

Scriptable options need no change: ctx.raw is the same node object it always was. Two things do:

tooltip: {
callbacks: {
label: (item) => item.dataset.data[item.dataIndex].v,
label: (item) => item.parsed.v,
}
}
datalabels: {
formatter: (value) => value.v,
formatter: (_value, ctx) =>
ctx.chart.getDatasetMeta(ctx.datasetIndex).controller.getParsed(ctx.dataIndex).v,
}

Any plugin that walks dataset.data alongside getDatasetMeta(i).data will see different lengths whenever the chart has groups.

The empty data: [] workaround is gone. A nested object needs its type spelled out, either through the chart’s generic or by flattening it up front:

new Chart<'treemap', MyRow[]>(ctx, { data: { datasets: [{ data: myTree }] } })
// or
import { flattenTree } from 'chartjs-chart-treemap'
const data = flattenTree<MyRow>(myTree, ['value'], 'name')

rtl, spacing, unsorted and displayMode shape the whole layout, so they are dataset options and are no longer read from options.elements.treemap.

options: {
elements: { treemap: { spacing: 2, rtl: true } },
datasets: { treemap: { spacing: 2, rtl: true } },
}

Setting them on the dataset itself worked in v4 and still works.

The colours, borders, captions and labels are element options and are unchanged.

A divider drew one line across the middle of a group regardless of how many children it had. Outline groups with a scriptable borderWidth instead, keyed on the group level:

borderWidth: (ctx) => (ctx.raw && ctx.raw.l === 0 ? 3 : 0.5),

The Outlining Groups sample shows it.

Text with overflow: 'cut' used to run through the padding region and stop at the element’s border. It now stops at the padding. Set padding: 0 to get the v4 look back.

Captions in headerBoxes mode are unaffected: their strip is sized from their own line height, so only the horizontal inset applies.

None of this is required, but it is why the release exists:

  • wrap breaks a label to the width of its box, and overflow: 'ellipsis' marks what did not fit.
  • textAlign aligns the lines within the block, separately from where align puts the block.
  • valueScale compresses a range so one dominant value does not hide the rest, and others collapses a long tail into one named tile.
  • region gives a dataset its own part of the chart area, so two of them can sit side by side.
  • Captions accept overflow, and a newline in a string starts a new line.