Angular ChartsTreemap 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. 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 each 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 used with linear data or, in other words, arrays. Since treemaps are used to render tree data, to create a basic treemap, we need to use a hierarchy chart.

A basic treemap configuration would look like this:

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 sizeKey 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:

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
    groupFill: 'black',  // the color of group tiles, retrieved from data if `undefined`
    colorDomain: [0, 2, 4], // depth of 0 will correspond to 'red', 2 to 'green' and so on
    colorRange: ['red', 'green', 'blue'], // tiles with a depth of 1 will be a blend of 'red' and 'green'
    // change the color of a particular tile
    formatter: ({ datum, labelKey, highlighted }) => {
        if (datum[labelKey] === 'Joel Cooper') {
            return { fill: highlighted ? 'white' : 'orchid' };
        }
    },
}]

Organizational Chart Example

Understanding the Treemap colours

There are several ways to customise the colours of treemap tiles.

Storing the colour values in the data

If treemap data nodes have fill colours assigned to them, the property containing the colour should be specified in colorKey.

series: [{
    type: 'treemap',
    colorKey: 'color',
    data: [{
        children: [
            { color: 'red' },
            { color: '#fa5310' },
        ],
    }],
}]

Using the color scale

colorKey can also specify a property containing a numeric value. In this case the colorDomain and colorRange should be provided.

series: [{
    type: 'treemap',
    colorKey: 'color',
    colorDomain: [0, 10, 20],
    colorRange: ['red', 'yellow', 'green'],
    data: [{
        children: [
            { color: 5 },
            { color: 8 },
            { color: 12 },
        ],
    }],
}]

Groups colours

The groups can be coloured in 2 ways:

A static colour value can be specified in groupFill property.
If groupFill can be set to undefined, the group colour behaviour will match the one for tiles.

series: [{
    type: 'treemap',
    colorKey: 'color',
    groupFill: 'black',
    ...
    groupFill: undefined,
    data: [{
        color: 'black',
        children: [
            { color: 'white' },
            { color: 'red' },
            { color: 'white' },
        ],
    }],
}]

Strokes

There are several properties to control the tiles' and groups' stroke colors and widths.

series: [{
    type: 'treemap',
    tileStroke: 'black',
    tileStrokeWidth: 2,
    groupStroke: 'transparent',
    groupStrokeWidth: 0,
}]

Labels colours and font styles

Since tiles can have different sizes depending on layout, there is large, medium and small label configuration to match a specific size. Tiles can also have separate value labels. The styles for all of them can be specified like:

series: [{
    type: 'treemap',
    labels: {
        large: {
            color: 'black',
            fontWeight: 'bold',
        },
        medium: {
            color: 'black',
        },
        small: {
            color: 'gray',
            fontSize: 8,
        },
        value: {
            formatter: ({ datum }) => `${datum.size * 100}%`,
            style: {
                color: 'orange',
            },
        },
    },
}]

In addition the groups' titles can have their own styles:

series: [{
    type: 'treemap',
    title: {
        color: 'black',
        fontWeight: 'bold',
    },
    subtitle: {
        color: 'black',
        fontSize: 8,
    },
}]

Overriding the styles for particular tiles

Use formatter function to change a colour for specific tiles.

series: [{
    formatter: ({ datum, depth, labelKey, highlighted }) => {
        if (datum[labelKey] === 'Joel Cooper') {
            return { fill: highlighted ? 'white' : 'orchid' };
        }
    },
}]

Please see the API reference for more information.

Complex Colouring Chart Example

Tooltips

With no tooltip or series[].tooltip configuration, tooltip content will be taken from series values:

series[].labelKey will be displayed as tooltip title.
series[].labels.value.name will be displayed as tooltip content.
series[].labels.value.key will be displayed as additional tooltip content with a : prefix to separate it from the previous content.
series[].labels.value.formatter allows formatting of the additional tooltip content.

For more advanced configuration see the Tooltips section.

Padding

There are some properties to control the spacing of treemap tiles:

nodeGap controls the gap between the treemap tiles. This is the space between the sibling tiles within their parent.
nodePadding controls the padding of the inner content of treemap tiles. This is the space between the border of each tile and the contained labels and tiles.

series: [{
    ...
    nodeGap: 10,
    nodePadding: 20,
}]

API Reference

Properties available on the AgTreemapSeriesOptions<DatumType = any> interface.

type Type'treemap'	'treemap'
title TypeAgTreemapSeriesLabelOptions	The label configuration for the top-level tiles.
subtitle TypeAgTreemapSeriesLabelOptions	The label configuration for the children of the top-level parent tiles.
labels TypeAgTreemapSeriesLabelsOptions<DatumType>	Configuration for the tile labels.
labelKey Typestring Defaultlabel	The name of the node key containing the label.
sizeKey Typestring Defaultsize	The name of the node key containing the size value.
colorKey Typestring Defaultcolor	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.
colorDomain Typenumber[] Default["-5", "5"]	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.
colorRange Typestring[] Default["#cb4b3f", "#6acb64"]	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'.
groupFill Typestring Default#272931	The group fill color. If undefined the value based on `colorKey` will be used.
groupStroke Typestring	The group's stroke color.
groupStrokeWidth Typenumber	The group's stroke width.
tileStroke Typestring	The tile's stroke color.
tileStrokeWidth Typenumber	The tile's stroke width.
tooltip TypeAgTreemapSeriesTooltip<DatumType>	Series-specific tooltip configuration.
nodePadding TypePixelSize Default20	The amount of padding in pixels inside of each treemap tile.
nodeGap TypePixelSize Default0	The amount of gap in pixels between treemap tiles.
gradient Typeboolean Default	Whether or not to use gradients for treemap tiles.
tileShadow TypeAgDropShadowOptions	Configuration for the shadow used behind the treemap tiles.
labelShadow TypeAgDropShadowOptions	Configuration for the shadow used behind the treemap labels.
highlightGroups Typeboolean	Determines whether the groups will be highlighted by cursor.
highlightStyle TypeAgTreemapSeriesHighlightStyle	Configuration for treemap tiles when they are hovered over.
formatter TypeFunction	A callback function for adjusting the styles of a particular treemap tile based on the input parameters
listeners TypeAgSeriesListeners<DatumType>	A map of event names to event listeners.
id Typestring	Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value. Default: auto-generated value
data TypeDatumType[]	The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible Typeboolean	Whether or not to display the series.
showInLegend Typeboolean	Whether or not to include the series in the legend.
cursor Typestring	The cursor to use for hovered area markers. This config is identical to the CSS `cursor` property.
nodeClickRange TypeAgChartInteractionRange	Range from a node a click triggers the listener.

Basic Configuration

Stock Market Index Example

Alternative Configuration

Organizational Chart Example

Understanding the Treemap colours

Storing the colour values in the data

Using the color scale

Groups colours

Strokes

Labels colours and font styles

Overriding the styles for particular tiles

Complex Colouring Chart Example

Tooltips

Padding

API Reference

type

title

subtitle

labels

labelKey

sizeKey

colorKey

colorDomain

colorRange

groupFill

groupStroke

groupStrokeWidth

tileStroke

tileStrokeWidth

tooltip

nodePadding

nodeGap

gradient

tileShadow

labelShadow

highlightGroups

highlightStyle

formatter

listeners

id

data

visible

showInLegend

cursor

nodeClickRange