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,
series: [{
type: 'treemap',
labelKey: 'label',
sizeKey: 'size',
colorKey: '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,
colorKey: undefined,
groupFill: 'black',
colorDomain: [0, 2, 4],
colorRange: ['red', 'green', 'blue'],
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
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.
API Reference
Properties available on the AgTreemapSeriesOptions<DatumType = any> interface.
| 'treemap' | 'treemap' |
| AgTreemapSeriesLabelOptions | The label configuration for the top-level tiles. title: AgTreemapSeriesLabelOptions;
interface AgTreemapSeriesLabelOptions {
// The amount of the tile's vertical space to reserve for the label.
padding?: number;
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
type FontStyle =
'normal'
| 'italic'
| 'oblique'
type FontWeight =
'normal'
| 'bold'
| 'bolder'
| 'lighter'
| '100'
| '200'
| '300'
| '400'
| '500'
| '600'
| '700'
| '800'
| '900'
type FontSize = number
type FontFamily = string
type CssColor = string
|
| AgTreemapSeriesLabelOptions | The label configuration for the children of the top-level parent tiles. subtitle: AgTreemapSeriesLabelOptions;
interface AgTreemapSeriesLabelOptions {
// The amount of the tile's vertical space to reserve for the label.
padding?: number;
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
type FontStyle =
'normal'
| 'italic'
| 'oblique'
type FontWeight =
'normal'
| 'bold'
| 'bolder'
| 'lighter'
| '100'
| '200'
| '300'
| '400'
| '500'
| '600'
| '700'
| '800'
| '900'
type FontSize = number
type FontFamily = string
type CssColor = string
|
| AgTreemapSeriesLabelsOptions | Configuration for the tile labels. labels: AgTreemapSeriesLabelsOptions;
interface AgTreemapSeriesLabelsOptions {
// The label configuration for the large leaf tiles.
large?: AgChartLabelOptions;
// The label configuration for the medium-sized leaf tiles.
medium?: AgChartLabelOptions;
// The label configuration for the small leaf tiles.
small?: AgChartLabelOptions;
// The configuration for the cell value label.
value?: { key?: string; name?: string; formatter?: (params: { datum: any; }) => string | undefined; style?: AgChartLabelOptions; };
}
interface AgChartLabelOptions {
// Whether or not the labels should be shown.
enabled?: boolean;
// The font style to use for the labels.
fontStyle?: FontStyle;
// The font weight to use for the labels.
fontWeight?: FontWeight;
// The font size in pixels to use for the labels.
fontSize?: FontSize;
// The font family to use for the labels.
fontFamily?: FontFamily;
// The colour to use for the labels.
color?: CssColor;
}
type FontStyle =
'normal'
| 'italic'
| 'oblique'
type FontWeight =
'normal'
| 'bold'
| 'bolder'
| 'lighter'
| '100'
| '200'
| '300'
| '400'
| '500'
| '600'
| '700'
| '800'
| '900'
type FontSize = number
type FontFamily = string
type CssColor = string
|
| string | The name of the node key containing the label. Default: 'label' |
| string | The name of the node key containing the size value. Default: 'size' |
| 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] |
| 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'] |
| string | The group fill color. If undefined the value based on colorKey will be used. Default: '#272931' |
| string | The group's stroke color. |
| number | The group's stroke width. |
| string | The tile's stroke color. |
| number | The tile's stroke width. |
| AgTreemapSeriesTooltip<DatumType> | Series-specific tooltip configuration. tooltip: AgTreemapSeriesTooltip<DatumType>;
interface AgTreemapSeriesTooltip<DatumType> {
// Function used to create the content for tooltips.
renderer?: (params: AgTreemapSeriesTooltipRendererParams<DatumType>) => string | AgTooltipRendererResult;
// Whether or not to show tooltips when the series are hovered over.
enabled?: boolean;
// The position of the tooltip. By default the tooltip follows the mouse pointer.
position?: AgTooltipPositionOptions;
// Configuration for tooltip interaction.
interaction?: AgSeriesTooltipInteraction;
}
interface AgTreemapSeriesTooltipRendererParams<DatumType> {
// Datum from the series data that the treemap tile is being rendered for.
datum: DatumType;
// The parent of the datum from the treemap data.
parent?: DataValue;
// The depth of the datum in the hierarchy.
depth: number;
// sizeKey as specified on series options.
sizeKey?: string;
// labelKey as specified on series options.
labelKey?: string;
// colorKey as specified on series options.
colorKey?: string;
// The computed fill colour of the treemap tile.
color?: string;
// The title of the treemap tile
title?: string;
// The ID of the series.
seriesId: string;
}
type DataValue = any
interface AgTooltipRendererResult {
// Title text for the tooltip header.
title?: string;
// Content text for the tooltip body.
content?: string;
// Tooltip title text color.
color?: string;
// Tooltip title background color.
backgroundColor?: string;
}
type AgTooltipPositionOptions =
AgMovingTooltipPositionOptions
interface AgMovingTooltipPositionOptions {
// The type of positioning for the tooltip. By default, the tooltip follows the pointer.
type: AgTooltipPositionType;
// The horizontal offset in pixels for the position of the tooltip.
xOffset?: PixelSize;
// The vertical offset in pixels for the position of the tooltip.
yOffset?: PixelSize;
}
type AgTooltipPositionType = 'pointer' | 'node'
type PixelSize = number
interface AgSeriesTooltipInteraction {
// Set to true to keep the tooltip open when the mouse is hovering over it, and enable clicking tooltip text
enabled: boolean;
}
|
| PixelSize | The amount of padding in pixels inside of each treemap tile. Increasing nodePadding will reserve more space for parent labels. nodePadding: PixelSize;
type PixelSize = number
|
| boolean | Whether or not to use gradients for treemap tiles. Default: true |
| tileShadow
AgDropShadowOptions | Configuration for the shadow used behind the treemap tiles. tileShadow: AgDropShadowOptions;
interface AgDropShadowOptions {
// Whether or not the shadow is visible.
enabled?: boolean;
// The colour of the shadow.
color?: CssColor;
// The horizontal offset in pixels for the shadow.
xOffset?: PixelSize;
// The vertical offset in pixels for the shadow.
yOffset?: PixelSize;
// The radius of the shadow's blur, given in pixels.
blur?: PixelSize;
}
type CssColor = string
type PixelSize = number
|
| labelShadow
AgDropShadowOptions | Configuration for the shadow used behind the treemap labels. labelShadow: AgDropShadowOptions;
interface AgDropShadowOptions {
// Whether or not the shadow is visible.
enabled?: boolean;
// The colour of the shadow.
color?: CssColor;
// The horizontal offset in pixels for the shadow.
xOffset?: PixelSize;
// The vertical offset in pixels for the shadow.
yOffset?: PixelSize;
// The radius of the shadow's blur, given in pixels.
blur?: PixelSize;
}
type CssColor = string
type PixelSize = number
|
| boolean | Determines whether the groups will be highlighted by cursor. |
| AgTreemapSeriesHighlightStyle | Configuration for treemap tiles when they are hovered over. highlightStyle: AgTreemapSeriesHighlightStyle;
interface AgTreemapSeriesHighlightStyle {
// Highlight style used for a text when item is tapped or hovered over.
text?: AgTreemapSeriesHighlightTextStyle;
// Highlight style used for an individual marker when tapped or hovered over.
item?: AgSeriesHighlightMarkerStyle;
// Highlight style used for whole series when one of its markers is tapped or hovered over.
series?: AgSeriesHighlightSeriesStyle;
}
interface AgTreemapSeriesHighlightTextStyle {
// The colour of an item's text when tapped or hovered over. Use `undefined` for no highlight.
color?: CssColor;
}
type CssColor = string
interface AgSeriesHighlightMarkerStyle {
// The fill colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
fill?: CssColor;
// The opacity of the fill for the highlighted item.
fillOpacity?: Opacity;
// The stroke colour of a marker when tapped or hovered over. Use `undefined` for no highlight.
stroke?: CssColor;
// The stroke width of a marker when tapped or hovered over. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
type Opacity = number
type PixelSize = number
interface AgSeriesHighlightSeriesStyle {
enabled?: boolean;
// The opacity of the whole series (area line, area fill, labels and markers, if any) when another chart series or another stack level in the same area series is highlighted by hovering a data point or a legend item. Use `undefined` or `1` for no dimming.
dimOpacity?: Opacity;
// The stroke width of the area line when one of the markers is tapped or hovered over, or when a tooltip is shown for a data point, even when series markers are disabled. Use `undefined` for no highlight.
strokeWidth?: PixelSize;
}
|
| Function | A callback function for adjusting the styles of a particular treemap tile based on the input parameters formatter = (
params: AgTreemapSeriesFormatterParams<DataValue>
) => AgTreemapSeriesFormat;
interface AgTreemapSeriesFormatterParams<DataValue = any> {
// Datum from the series data that the treemap tile is being rendered for.
datum: DataValue;
// The parent of the datum from the treemap data.
parent?: DataValue;
// The depth of the datum in the hierarchy.
depth: number;
// labelKey as specified on series options.
labelKey: string;
// sizeKey as specified on series options.
sizeKey?: string;
// colorKey as specified on series options.
colorKey?: string;
// The colour of the fill for the treemap tile.
fill?: CssColor;
// The opacity of the fill for the treemap tile.
fillOpacity?: Opacity;
// The colour of the stroke for the treemap tile.
stroke?: CssColor;
// The opacity of the stroke for the treemap tile.
strokeOpacity?: Opacity;
// The width in pixels of the stroke for the treemap tile.
strokeWidth?: PixelSize;
// Whether or not the gradients are used for treemap tiles.
gradient?: boolean;
// `true` if the tile is highlighted by hovering
highlighted: boolean;
// The ID of the series.
seriesId: string;
}
type DataValue = any
type CssColor = string
type Opacity = number
type PixelSize = number
interface AgTreemapSeriesFormat {
// The colour of the fill for the treemap tile.
fill?: CssColor;
// The opacity of the fill for the treemap tile.
fillOpacity?: Opacity;
// The colour of the stroke for the treemap tile.
stroke?: CssColor;
// The opacity of the stroke for the treemap tile.
strokeOpacity?: Opacity;
// The width in pixels of the stroke for the treemap tile.
strokeWidth?: PixelSize;
// Whether or not the gradient is used for the treemap tile.
gradient?: boolean;
}
|
| AgSeriesListeners<DatumType> | A map of event names to event listeners. listeners: AgSeriesListeners<DatumType>;
interface AgSeriesListeners<DatumType> {
// The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is clicked.
nodeClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
// The listener to call when a node (marker, column, bar, tile or a pie sector) in the series is double clicked.
nodeDoubleClick?: (params: AgSeriesNodeClickParams<DatumType>) => void;
}
interface AgSeriesNodeClickParams<DatumType> {
// Event type.
type: 'nodeClick';
// Series ID, as specified in series.id (or generated if not specified)
seriesId: string;
// Datum from the series data array.
datum: DatumType;
// xKey as specified on series options
xKey?: string;
// yKey as specified on series options
yKey?: string;
// sizeKey as specified on series options
sizeKey?: string;
// labelKey as specified on series options
labelKey?: string;
// colorKey as specified on series options
colorKey?: string;
// angleKey as specified on series options
angleKey?: string;
// calloutLabelKey as specified on series options
calloutLabelKey?: string;
// sectorLabelKey as specified on series options
sectorLabelKey?: string;
// radiusKey as specified on series options
radiusKey?: string;
}
|
| string | 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
|
| DatumType[] | The data to use when rendering the series. If this is not supplied, data must be set on the chart instead. |
| boolean | Whether or not to display the series. |
| boolean | Whether or not to include the series in the legend. |
| string | The cursor to use for hovered area markers. This config is identical to the CSS cursor property. |
| AgChartInteractionRange | Range from a node a click triggers the listener. nodeClickRange: AgChartInteractionRange;
type AgChartInteractionRange =
PixelSize
| 'exact'
| 'nearest'
type PixelSize = number
|
