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.
Cheat sheet
Section titled “Cheat sheet”| 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 |
Chart.js 4 is required
Section titled “Chart.js 4 is required”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.
data replaces tree
Section titled “data replaces tree”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.
dataset.data is your rows now
Section titled “dataset.data is your rows now”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.
TypeScript
Section titled “TypeScript”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 }] } })
// orimport { flattenTree } from 'chartjs-chart-treemap'const data = flattenTree<MyRow>(myTree, ['value'], 'name')Layout options moved to the dataset scope
Section titled “Layout options moved to the dataset scope”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.
dividers is removed
Section titled “dividers is removed”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 is clipped at the padding
Section titled “Text is clipped at the padding”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.
What is new
Section titled “What is new”None of this is required, but it is why the release exists:
wrapbreaks a label to the width of its box, andoverflow: 'ellipsis'marks what did not fit.textAlignaligns the lines within the block, separately from wherealignputs the block.valueScalecompresses a range so one dominant value does not hide the rest, andotherscollapses a long tail into one named tile.regiongives 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.