chartjs-chart-treemap

When defining a treemap hierarchy using the groups option, you can include missing levels in your data. The treemap plugin automatically skips null, undefined, and empty group values. This allows a branch to continue directly to the next available group level without requiring a complete hierarchy for every data point.

const data = [
  // 'component' and 'subFolder' are null, so the hierarchy skips directly from 'folder' to 'file'
  { folder: './src', component: null, subFolder: null, file: 'index.js', value: 6 },
  // 'subFolder' is null, so it skips from 'component' to 'file'
  { folder: './src', component: 'A', subFolder: null, file: 'A.js', value: 8 },
];

const config = {
  type: 'treemap',
  data: {
    datasets: [{
      tree: data,
      key: 'value',
      groups: ['folder', 'component', 'subFolder', 'file'],
    }]
  }
};

To create a treemap, you must register the TreemapController and TreemapElement alongside the standard Chart.js registerables. Set the chart type to 'treemap' and provide your hierarchical data in the tree property within the dataset object.

import { Chart, registerables } from 'chart.js';
import { TreemapController, TreemapElement } from 'chartjs-chart-treemap';

Chart.register(...registerables, TreemapController, TreemapElement);

new Chart(document.getElementById('chart'), {
  type: 'treemap',
  data: {
    datasets: [
      {
        tree: [6, 6, 4, 3, 2, 2, 1],
        backgroundColor: 'rgba(54, 162, 235, 0.6)',
      },
    ],
  },
});

To enable zooming and panning in a treemap chart, you must configure the zoom plugin within the options.plugins object. The plugin supports specific sub-configurations for zoom (e.g., enabling mouse wheel interaction) and pan (enabling dragging to move the view).

const config = {
  type: 'treemap',
  data: {
    datasets: [
      {
        label: 'My First dataset',
        tree: Utils.numbers(NUMBER_CFG),
        // ... other dataset properties
      }
    ],
  },
  options: {
    plugins: {
      zoom: {
        zoom: {
          wheel: {
            enabled: true,
          }
        },
        pan: {
          enabled: true,
        }
      }
    }
  }
};

To use treemap charts in your project, install the chartjs-chart-treemap package using npm. This extension is compatible with Chart.js v3.8+ and v4+.

npm install chartjs-chart-treemap

To use the treemap plugin in a plain HTML environment without a module bundler, load the Chart.js library first, followed by the chartjs-chart-treemap plugin via their respective minified script files. Once loaded, you can initialize a chart by setting the type to 'treemap' in the Chart constructor.

<script src="path/to/chartjs/dist/chart.min.js"></script>
<script src="path/to/chartjs-chart-treemap/dist/chartjs-chart-treemap.min.js"></script>
<script>
    let myChart = new Chart(ctx, {type: 'treemap', ...});
</script>

You can create a hierarchical treemap by providing an array of keys to the groups option within a dataset. Each string in the array represents a level of nesting in the hierarchy. For example, groups: ['region', 'division'] will first group data by region, and then sub-group those regions by division.

When using groups, the tree property should contain the hierarchical data structure, and the key property specifies which numeric value determines the size of the rectangles at each level.

const config = {
  type: 'treemap',
  data: {
    datasets: [{
      tree: Data.statsByState,
      key: 'area',
      groups: ['region', 'division'],
      spacing: 1,
      borderWidth: 0.5,
      borderColor: 'rgba(200,200,200,1)',
      backgroundColor: 'rgba(220,230,220,0.3)',
      hoverBackgroundColor: 'rgba(220,230,220,0.5)',
    }]
  },
  options: {
    // ...
  }
};

To use the module via CDN, include both the Chart.js script and the chartjs-chart-treemap script in your HTML file.

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script src="https://cdn.jsdelivr.net/npm/chartjs-chart-treemap"></script>

Because the treemap controller builds the data array from the tree property at runtime, TypeScript definitions require the data property to be present on every dataset. To satisfy this without providing actual data (which is handled by the controller), provide an empty array to the data property.

const dataset = {
  data: [],
  tree: [15, 6, 6, 5, 4, 3, 2, 2],
};

When using modern module bundlers, import the necessary components from both chart.js and chartjs-chart-treemap. You must register the TreemapController and TreemapElement along with the standard Chart.js registerables to enable the treemap functionality.

import {Chart, registerables} from 'chart.js';
import {TreemapController, TreemapElement} from 'chartjs-chart-treemap';

Chart.register(...registerables, TreemapController, TreemapElement);