chartjs-chart-treemap

chartjs-chart-treemap extends Chart.js with a new treemap controller and element type, letting you plot hierarchical or flat datasets as a grid of proportionally sized rectangles using the classic squarified treemap algorithm. It plugs directly into Chart.js’s existing scale, animation, tooltip, and options-resolution systems rather than reimplementing them, so treemap charts behave like any other Chart.js dataset — scriptable options, per-element styling, and shared tooltip positioning all work out of the box.

The library supports multi-level grouping (drilling a flat array into nested boxes by one or more group keys), captions and labels with custom formatters, configurable spacing and border radius, and RTL layouts. It ships as ESM, CommonJS, and a UMD/minified browser build, with full TypeScript typings, making it a drop-in addition for dashboards, file-size explorers, portfolio breakdowns, or any UI that needs to show part-to-whole relationships across a hierarchy.

What You Get

• A registrable TreemapController and TreemapElement that plug into any Chart.js v3.8+/v4 chart via Chart.register
• A squarified treemap layout engine (squarify.ts) that packs values into rectangles while minimizing aspect-ratio distortion
• Multi-level grouping support — nest data by one or more group keys to produce drill-down style boxes
• Built-in captions and labels with scriptable formatter functions, padding, alignment, and multi-line overflow handling
• Configurable spacing, border width/radius, and RTL-aware layout
• First-class TypeScript typings and ESM/CJS/UMD builds published to npm and jsDelivr/unpkg

Common Use Cases

• Disk or file-size explorers showing directory/file hierarchies sized by bytes
• Portfolio or budget breakdowns showing allocation proportions across categories and sub-categories
• Market-share or org-structure dashboards where nested groups need to be visualized by relative size
• Any dashboard already using Chart.js that needs to add a part-to-whole hierarchical view without adopting a separate charting library

Under The Hood

Architecture The module is a plugin-style extension of Chart.js: src/controller.ts defines a TreemapController (a DatasetController subclass) that overrides configure, update, updateElements, and draw to compute rectangle layouts and feed them through Chart.js’s normal scale/animation pipeline, while src/element.ts defines a TreemapElement (an Element subclass) that knows how to draw a single rectangle plus its caption/labels/dividers. The layout math itself is isolated in src/squarify.ts, which implements the classic squarified treemap algorithm using a small Rect/StatArray helper pair (src/rect.ts, src/statArray.ts) to track running aspect-ratio statistics per row. controller.ts’s buildData function recursively re-squarifies sub-rectangles per group level when dataset.groups is set, producing nested boxes; this recursive-rect-subdivision is the one piece that would ripple outward if the grouping model changed. Tooltip positioning is registered defensively (registerTooltipPositioner) so it works regardless of whether the tooltip plugin or the treemap controller registers first.

Tech Stack Written in TypeScript (~67% of the codebase) with a chart.js peer dependency (>=3.0.0, developed against 4.x) and no other runtime dependencies. The build pipeline uses Rollup with @rollup/plugin-swc for compilation, emitting ESM, CJS, and a minified UMD bundle plus .d.ts declarations via tsc --emitDeclarationOnly. Linting/formatting is handled by Biome. Documentation is an Astro + Starlight static site (docs/) built from the same repo and deployed to Cloudflare Pages, with releases automated via semantic-release.

Code Quality Tests are organized into unit specs (*.test.ts files colocated with source, run under Jasmine via c8 for coverage), visual fixture tests (test/fixtures/, driven by Karma against real browsers with pixel-diffing via pixelmatch), and separate Node ESM/CJS integration smoke tests. This is a notably thorough setup for a chart plugin — unit, visual-regression, and packaging-integration tests all run in CI. Typing is strict TypeScript with a dedicated tsconfig.test.json and test/types/ type-check fixtures; git hooks are wired via .githooks and enforced through npm run prepare.

What Makes It Unique Unlike general-purpose treemap libraries (e.g. D3-based ones), this module reuses Chart.js’s existing scale, animation, tooltip, and scriptable-options machinery instead of building a parallel rendering stack — a treemap dataset gets Chart.js’s standard interaction modes, responsive resizing, and plugin ecosystem (datalabels, zoom) for free. Its recursive multi-level grouping (via dataset.groups) lets a single flat dataset be re-squarified per group boundary to produce nested drill-down boxes, which is more configurable than most treemap implementations that only support a single level of nesting.