The Map Line Series visualises geographic lines, such as roads or flight paths, with the ability to vary width and colour to represent data values.
Simple Map Lines
To create a Map Line Series, use the map-line
series type and provide data and topology. These can be provided in either the chart or series objects.
A Map Line Series should be combined with a Map Shape Background Series.
data: data,
topology: topology,
series: [
{
type: "map-shape-background",
topology: backgroundTopology,
},
{
type: "map-line",
idKey: "name",
},
],
In this configuration:
- Both the
topology
anddata
for themap-line
series are provided on the chart level. idKey
defines 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.- The
map-shape-background
series has its topology defined on the series level. - The
map-shape-background
series is rendered behind themap-line
series due to their order in the series array.
Colour Scale
To colour the lines based on the magnitude of the data, use colorKey
.
series: [
{
type: 'map-line',
idKey: 'name',
colorKey: 'dailyVehicles',
colorName: 'Daily Vehicles'
},
],
In this configuration:
colorKey
is set to 'dailyVehicles', which supplies numerical values for the colour scale.colorName
is optional and configures the display name reflected in Tooltips.
See Colour Range and Gradient Legend for more details about customising these features.
Proportional Line Width
To vary the width of the line to denote the magnitude of the data values use sizeKey
, strokeWidth
and maxStrokeWidth
.
series: [
{
type: 'map-line',
idKey: 'name',
sizeKey: 'dailyVehicles',
sizeName: 'Daily Vehicles',
strokeWidth: 1,
maxStrokeWidth: 3,
},
],
In this configuration:
sizeKey
is set to 'dailyVehicles', which supplies numerical values for the size scale.sizeName
is optional and configures the display name reflected in Tooltips.strokeWidth
is used for the smallest value in the size scale.maxStrokeWidth
is used for the largest value in the size scale.
Background Lines
The Map Line Background series displays all the lines of a topology without requiring any data.
This can be useful to provide context for other series.
series: [
{
type: 'map-line-background',
topology: backgroundTopology,
},
// ...
],
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 AgMapLineSeriesOptions
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 key to use to retrieve size values from the data, used to control the width of the stroke.
The name of the node key containing the colour value. This value (along with colorRange
config) will be used to determine the colour of the stroke.
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 size 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.
A callback function for adjusting the styles of a particular Map line based on the input parameters.
Properties available on the AgMapLineBackgroundOptions
interface.