AG Grid
Results:
Loading...
Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

Vue Charts: Treemap Series

Treemap series is used to render hierarchical data structures or trees, where each node in the tree is represented by a rectangle, and the value of a node by the area of its rectangle.

The bigger the value, the bigger the rectangle is relative to its siblings. Also, parent nodes are represented by rectangles with areas that are the totals of their children.

If the nodes have no value, then their area is divided equally among siblings within their parent node.

The Ag-Charts treemap series uses a popular "squarified" tiling algorithm which tries to keep eash node's rectangle as square as possible.

Treemap series would be a great fit for visualizing a directory structure (the original purpose of the algorithm), components of a stock market index, shares of products within product categories, or sales breakdown by city, state, and country. And these are just a few examples.

Basic Configuration

cartesian and polar charts are meant to be used with linear data or, in other words, arrays. But since treemaps are used to render tree data, to create a basic treemap we need to use another type of chart, a hierarchy chart. A basic treemap configuration would therefore look like this:

type: 'hierarchy',
data, // the root node of the hierarchy
series: [{
    type: 'treemap',
    labelKey: 'label', // the name of the key to fetch the label value from
    sizeKey: 'size',   // the name of the key to fetch the value that will determine tile size
    colorKey: 'color', // the name of the key to fetch the value that will determine tile color
}]

The data should be a tree structure, where parent nodes use the children property to list their children:

let data = {
    label: 'Root',
    children: [
        {
            label: 'Utilities',
            children: [{
                label: 'AWK',
                size: 252
            }]
        },
        ...
    ]
}

Notice, that only the leaf nodes of a tree are required to have the sizeKey property. The size of the parent nodes will be automatically determined.

The labelKey, sizeKey and colorKey configs can be omitted, if the node objects in your data happen to have the label, size and color fields.

Any treemap series covers the whole series area of a chart, so it doesn't make sense to have more than a single treemap series in a chart, even though it's technically supported.

Let's take a look at how we can use the treemap series to render a snapshot of the S&P 500 stock market index. Feel free to open this example in Plunker to enlarge the size of the component and notice how the treemap reveals more data as it grows bigger.

Stock Market Index Example

Alternative Configuration

Although not very common, treemaps can be used to show the hierarchy without emphasizing size. In such a case, you can set the colorKey to undefined. This will make all sibling tiles within the same parent have the same area (but not necessarily the same shape).

The org chart example below takes advantage of that by using the following config:

type: 'hierarchy',
data,
series: [{
    type: 'treemap',
    labelKey: 'orgHierarchy',
    sizeKey: undefined,  // make all siblings within a parent the same size
    colorKey: undefined, // use node depth value to determine the tile color
    colorParents: true,  // assign color to parent tiles based on their depth too (not just leaf tiles)
    colorDomain: [0, 2, 4], // depth of 0 will correspond to 'red', of 2 to 'green' and so on
    colorRange: ['red', 'green', 'blue'] // tiles with a depth of 1 will be a blend of 'red' and 'green'
}]

Organizational Chart Example

API Reference

title
The label configuration for the top-level parent tiles.
See title for more details.
subtitle
The label configuration for the children of the top-level parent tiles.
See subtitle for more details.
labels
Configuration for the tile labels.
See labels for more details.
labelKey
string
The name of the node key containing the label.
Default: 'label'
sizeKey
string
The name of the node key containing the size value.
Default: 'size'
colorKey
string
The name of the node key containing the color value. This value (along with colorDomain and colorRange configs) will be used to determine the tile color.
Default: 'color'
colorDomain
number[]
The domain the 'colorKey' values belong to. The domain can contain more than two stops, for example [-5, 0, -5]. In that case the 'colorRange' should also use a matching number of colors.
Default: '[-5, 5]'
colorRange
string[]
The color range to interpolate the numeric colorDomain into. For example, if the colorDomain is [-5, 5] and colorRange is ['red', 'green'], a colorKey value of -5 will be assigned the 'red' color, 5 - 'green' color and 0 a blend of 'red' and 'green'.
Default: '['#cb4b3f', '#6acb64']'
colorParents
boolean
Whether or not to assign colors to non-leaf nodes based on 'colorKey'.
Default: false
tooltip
Series-specific tooltip configuration.
See tooltip for more details.
nodePadding
number
The amount
Default: 2
gradient
boolean
Whether or not to use gradients for treemap tiles.
Default: true
cursor
string
The cursor to use for hovered treemap tiles. This config is identical to the CSS cursor property.
Default: 'default'

title

treemap > title

The label configuration for the top-level parent tiles.

treemap: {
  ...
  title: {
    color?: string; // default: 'white'
    fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
    fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
    fontSize?: number; // default: 12
    fontFamily?: string; // default: 'Verdana, sans-serif'
    padding?: number; // default: 15
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 12
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'
padding
number
The amount of the tile's vertical space to reserve for the label.
Default: 15

subtitle

treemap > subtitle

The label configuration for the children of the top-level parent tiles.

treemap: {
  ...
  subtitle: {
    color?: string; // default: 'white'
    fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
    fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
    fontSize?: number; // default: 9
    fontFamily?: string; // default: 'Verdana, sans-serif'
    padding?: number; // default: 13
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 9
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'
padding
number
The amount of the tile's vertical space to reserve for the label.
Default: 13

labels

treemap > labels

Configuration for the tile labels.

treemap: {
  ...
  labels: {
    large?: Large;
    medium?: Medium;
    small?: Small;
    color?: Color;
  }
}
large
The label configuration for the large leaf tiles.
See large for more details.
medium
The label configuration for the medium-sized leaf tiles.
See medium for more details.
small
The label configuration for the small leaf tiles.
See small for more details.
color
The configuration for the labels showing the value of the 'colorKey'.
See color for more details.

large

treemap > labels > large

The label configuration for the large leaf tiles.

treemap: {
  ...
  labels: {
    ...
    large: {
      color?: string; // default: 'white'
      fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
      fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
      fontSize?: number; // default: 18
      fontFamily?: string; // default: 'Verdana, sans-serif'
    }
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 18
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'

medium

treemap > labels > medium

The label configuration for the medium-sized leaf tiles.

treemap: {
  ...
  labels: {
    ...
    medium: {
      color?: string; // default: 'white'
      fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
      fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
      fontSize?: number; // default: 14
      fontFamily?: string; // default: 'Verdana, sans-serif'
    }
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 14
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'

small

treemap > labels > small

The label configuration for the small leaf tiles.

treemap: {
  ...
  labels: {
    ...
    small: {
      color?: string; // default: 'white'
      fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
      fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
      fontSize?: number; // default: 10
      fontFamily?: string; // default: 'Verdana, sans-serif'
    }
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 10
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'

color

treemap > labels > color

The configuration for the labels showing the value of the 'colorKey'.

treemap: {
  ...
  labels: {
    ...
    color: {
      color?: string; // default: 'white'
      fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
      fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'bold'
      fontSize?: number; // default: 12
      fontFamily?: string; // default: 'Verdana, sans-serif'
    }
  }
}
color
string
The colour of the text.
Default: 'white'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'bold'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 12
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'

tooltip

treemap > tooltip

Series-specific tooltip configuration.

treemap: {
  ...
  tooltip: {
    enabled?: boolean; // default: true
    renderer?: Function;
  }
}
enabled
boolean
Whether or not to show tooltips when the series are hovered over.
Default: true
renderer
Function
Function used to create the content for tooltips.
renderer = (params: RendererParams) => string;

interface RendererParams {
  datum: any;
  labelKey: string;
  sizeKey?: string;
  colorKey?: string;
}

Next Up

Continue to the next section to learn about bar and column series.