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 - Markers and Points of Interest

Version 14.2.0
Enterprise

The Map Marker Series visualises data for geographic points, with the ability to vary the size to represent data values.

Simple Map Markers Copy Link

To create a Map Marker Series, use the map-marker series type and provide data and topology. These can be provided in either the chart or series objects.

A Map Marker Series should be combined with a Map Shape Background Series.

data: data,
topology: topology,
series: [
    // ...
    {
        type: 'map-marker',
        idKey: 'name',
    },
]

In this configuration:

  • The topology and data are provided once 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.

Map Marker Position from Data Copy Link

Instead of using a topology file, the Map Marker Series can use geographic data from within the data. This is best suited for data containing latitude and longitude coordinates such as crime data.

 
data: data,
series: [
    // ...
    {
        type: 'map-marker',
        latitudeKey: 'lat',
        longitudeKey: 'lon',
    },
]

In this configuration:

  • No topology is required for the map-marker series.
  • latitudeKey and longitudeKey refer to fields in the provided data, and are used to position the marker.

Proportional Marker Size Copy Link

To vary the size of the marker to denote the magnitude of the data values use sizeKey, minSize and maxSize.

{
    series: [
        // ...
        {
            type: 'map-marker',
            latitudeKey: 'lat',
            longitudeKey: 'lon',
            sizeKey: 'count',
            sizeName: 'Count',
            minSize: 3,
            maxSize: 50,
        },
    ],
}

In this configuration:

  • sizeKey provides the numerical values determining the size of each marker.
  • sizeName is optional and configures the display name reflected in Tooltips.
  • minSize provides the size of the marker for the smallest data point. It defaults to size when not set.
  • maxSize provides the size for the largest data point.

When sizeKey is not set, size is used as the fixed size for every marker.

Customisation Copy Link

It is possible to customise the fill, stroke and shape of the markers, as well as to add labels. See the API Reference for more details.

API Reference Copy Link

Properties available on the AgMapMarkerSeriesOptions interface.

type required 'map-marker'
Configuration for the Map Marker 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.
latitudeKey DatumKey
The key to use to retrieve latitude values from the data, used to control the position of the markers.
longitudeKey DatumKey
The key to use to retrieve longitude values from the data, used to control the position of the markers.
sizeKey DatumKey
The key to use to retrieve size values from the data, used to control the size of the markers.
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 markers.
labelKey DatumKey
The key to use to retrieve values from the data to use as labels for the markers.
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.
latitudeName string
A human-readable description of the latitude values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
longitudeName string
A human-readable description of the longitude 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.
minSize PixelSize
Determines the smallest size a marker can be in pixels when `sizeKey` is present. Defaults to `size` when not set.
maxSize PixelSize
Determines the largest size a marker can be in pixels when `sizeKey` is present.
sizeDomain [AgNumericValue, AgNumericValue]
Explicitly specifies the extent of the domain of `sizeKey` values to map onto the `[minSize, maxSize]` range. Reverse the bounds (e.g. `[100, 0]`) to invert the mapping so that larger values produce smaller markers.
colorScale AgColorScale
Configuration for colour scale with fills, domain, and mode.
label AgMapMarkerSeriesLabel
Configuration for the labels shown on top of data points.
tooltip AgSeriesTooltip
Series-specific tooltip configuration.
itemStyler Styler
A callback function for adjusting the styles of a particular Map marker based on the input parameters.
highlight AgMultiSeriesHighlightOptions
Configuration for highlighting when a series or legend item is hovered over.
shape AgMarkerShape
The shape to use for the markers. You can also supply a custom marker by providing a `AgMarkerShapeFn` function.
size PixelSize
The size in pixels of the markers. Used as the fixed marker size only when `sizeKey` is absent; when `sizeKey` is present the scale lower bound is controlled by `minSize` instead.
fill AgColorType
The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
fillOpacity Opacity
The opacity of the fill colour.
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.