AG Studio Launch Week šŸš€šŸš€šŸš€ 28 Sep - 2 Oct 2026 šŸš€šŸš€šŸš€ Join now
AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
SearchāŒ˜ KCtrl K
What's New
Getting started
Quick StartKey FeaturesCommunity vs. Enterprise
AI Features
Skills
Core features
Specialised Charts
Org ChartQuadrant Chart
Series
BarLineAreaScatterBubblePieDonutCombinationBox PlotCandlestickOHLCHeatmapHistogramNightingaleRadar AreaRadar LineRadial BarRadial ColumnRange AreaRange BarWaterfallSunburstTreemapSankeyChordFunnelCone FunnelPyramid
Gauges
Radial GaugeLinear Gauge

JavaScript ChartsMaps - Routes and Connections

Version 14.2.0
Enterprise

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 Copy Link

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 and data for the map-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.

Colour Scale Copy Link

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 the Colour Scale page for more details about customising colours, discrete bins, and the Gradient Legend.

Proportional Line Width Copy Link

To vary the width of the line to denote the magnitude of the data values use sizeKey, minStrokeWidth and maxStrokeWidth.

{
    series: [
        {
            type: 'map-line',
            idKey: 'name',
            sizeKey: 'dailyVehicles',
            sizeName: 'Daily Vehicles',
            minStrokeWidth: 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.
  • minStrokeWidth is used for the smallest value in the size scale. It defaults to strokeWidth when not set.
  • maxStrokeWidth is used for the largest value in the size scale.

When sizeKey is not set, strokeWidth is used as the fixed width for every line.

Background Lines Copy Link

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 Copy Link

Properties available on the AgMapLineSeriesOptions interface.

type required 'map-line'
Configuration for the Map Line Series.
topology GeoJSON
GeoJSON data.
topologyIdKey string default: name
The property to reference in the topology to match up with data.
title string
The title to use for the series.
legendItemName string
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.
id string default: auto-generated value
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.
context ContextDefault
Context object to use in callbacks.
data DatumDefault[]
The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean
Whether to display the series.
cursor string
The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
selection AgSelectionOptions
Configuration for data selection.
nodeClickRange InteractionRange
Range from a node that a click triggers the listener.
showInLegend boolean
Whether to include the series in the legend.
listeners AgSeriesListeners
A map of event names to event listeners.
idKey DatumKey
The name of the node key containing the id value.
sizeKey DatumKey
The key to use to retrieve size values from the data, used to control the width of the stroke.
colorKey DatumKey
The name of the node key containing the colour value. This value (along with `colorScale` config) will be used to determine the colour of the stroke.
labelKey DatumKey
The key to use to retrieve values from the data to use as labels on top of lines.
idName string
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.
sizeName string
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.
colorName string
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.
labelName string
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.
minStrokeWidth PixelSize
Determines the smallest width a stroke can be in pixels when `sizeKey` is present. Defaults to `strokeWidth` when not set.
maxStrokeWidth PixelSize
Determines the largest width a stroke can be in pixels when `sizeKey` is present.
sizeDomain AgNumericValue[]
Explicitly specifies the extent of the domain of `sizeKey` values to map onto the `[minStrokeWidth, maxStrokeWidth]` range. Reverse the bounds (e.g. `[100, 0]`) to invert the mapping so that larger values produce thinner strokes.
label AgMapLineSeriesLabel
Configuration for the labels shown on top of the line.
tooltip AgSeriesTooltip
Series-specific tooltip configuration.
itemStyler Styler
A callback function for adjusting the styles of a particular Map line based on the input parameters.
colorScale AgColorScale
Configuration for colour scale with fills, domain, and mode.
highlight AgMultiSeriesHighlightOptions
Configuration for highlighting when a series or legend item is hovered over.
stroke AgCssColorOrRef
The colour for the stroke.
strokeWidth PixelSize
The width of the stroke in pixels.
strokeOpacity Opacity
The opacity of the stroke colour.
lineDash PixelSize[]
An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.

Properties available on the AgMapLineBackgroundOptions interface.

type required 'map-line-background'
Configuration for the Map Shape Background.
topology GeoJSON
GeoJSON data.
stroke AgCssColorOrRef
The colour for the stroke of the line. A colour string, or a theme-colour reference object.
strokeWidth PixelSize
The width of the stroke in pixels.
strokeOpacity Opacity
The opacity of the stroke colour.
lineDash PixelSize[]
An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.