React 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

index.tsx

import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { backgroundTopology } from "./backgroundTopology";
import { data } from "./data";
import { topology } from "./topology";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "UK Cities",
    },
    data,
    topology,
    series: [
      {
        type: "map-shape-background",
        topology: backgroundTopology,
      },
      {
        type: "map-marker",
        idKey: "name",
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);

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.

index.tsx

import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { backgroundTopology } from "./backgroundTopology";
import { data } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "Crime in Surrey",
    },
    data,
    series: [
      {
        type: "map-shape-background",
        topology: backgroundTopology,
      },
      {
        type: "map-marker",
        latitudeKey: "lat",
        longitudeKey: "lon",
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);

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

index.tsx

import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { AgCharts } from "ag-charts-react";
import {
  AgChartOptions,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { backgroundTopology } from "./backgroundTopology";
import { data } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  MapMarkerSeriesModule,
  MapShapeBackgroundSeriesModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "Crime in Surrey",
    },
    data,
    series: [
      {
        type: "map-shape-background",
        topology: backgroundTopology,
      },
      {
        type: "map-marker",
        latitudeKey: "lat",
        longitudeKey: "lon",
        sizeKey: "count",
        sizeName: "Count",
        minSize: 3,
        maxSize: 50,
      },
    ],
  });

  return <AgCharts options={options} />;
};

const root = createRoot(document.getElementById("root")!);
root.render(<ChartExample />);

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.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

React ChartsMaps - Markers and Points of Interest

Simple Map Markers Copy Link

Map Marker Position from Data Copy Link

Proportional Marker Size Copy Link

Customisation Copy Link

API Reference Copy Link