The Map Shape Series visualises data representing geographic areas such as countries, using colours to denote distinct series or the magnitude of the values.
Simple Map Shapes
To create a Map Shape Series, use the map-shape series type and provide data and topology. These can be provided in either the chart or series objects.
topology: topology,
series: [
{
type: 'map-shape',
data: pacific,
idKey: 'name',
title: 'Pacific'
},
// ...
],
legend: {
enabled: true,
}
In this example:
- The
topologyis provided once on the chart level, and thedatais provided in each series. idKeydefines the property key in the data that will be matched against the property value in the topology. See Connecting Data to Topology for more details.titleprovides a name for the series, and is used in the Legend and Tooltips.
Colour Scale
To colour the shapes based on the magnitude of the data, use colorKey.
series: [
{
type: 'map-shape',
idKey: 'name',
colorKey: 'gdp',
},
],
In this configuration:
colorKeyis set to 'gdp', which supplies numerical values for the colour scale.
See Colour Range and Gradient Legend for more details about customising these features.
Labels
series: [
{
type: 'map-shape',
idKey: 'name',
labelKey: 'code',
},
],
In this configuration:
labelKeydefines the variable used for the labels.
See Label options for options for handling long labels.
Background Shapes
The Map Shape Background series displays all the shapes of a topology without requiring any data.
This can be useful to show disabled Map Shape Series when toggled off in the legend, or to provide context to Map Line Series and Map Marker Series.
topology,
series: [
{
type: 'map-shape-background',
},
// ...
],
As this is a background series rather than a data series, many normal series behaviours are disabled - including interactivity and appearing in the legend.
API Reference
Properties available on the AgMapShapeSeriesOptions interface.
The text to display in the legend for this series.
If multiple series share this value, they will be merged for the legend toggle behaviour.
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.
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
The name of the node key containing the colour value. This value (along with colorRange config) will be used to determine the segment colour.
A human-readable description of the id-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
A human-readable description of the colour values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
A human-readable description of the label values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
The colour range to interpolate the numeric colour domain (min and max colorKey values) into.
A callback function for adjusting the styles of a particular Map shape based on the input parameters.
Properties available on the AgMapShapeBackgroundOptions interface.