React ChartsMaps - Geographic Areas

Version 14.2.0

Enterprise

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 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,
  MapShapeSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { central, eastern, mountain, pacific } from "./data";
import { topology } from "./topology";

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

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "Timezones Across America",
    },
    topology,
    series: [
      {
        type: "map-shape",
        data: pacific,
        idKey: "name",
        title: "Pacific",
      },
      {
        type: "map-shape",
        data: mountain,
        idKey: "name",
        title: "Mountain",
      },
      {
        type: "map-shape",
        data: central,
        idKey: "name",
        title: "Central",
      },
      {
        type: "map-shape",
        data: eastern,
        idKey: "name",
        title: "Eastern",
      },
    ],
    legend: {
      enabled: true,
    },
  });

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

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

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 topology is provided once on the chart level, and the data is provided in each series.
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.
title provides a name for the series, and is used in the Legend and Tooltips.

Colour Scale 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,
  GradientLegendModule,
  MapShapeSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { DataType, data } from "./data";
import { topology } from "./topology";

const numberFormatter = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  useGrouping: true,
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  GradientLegendModule,
  MapShapeSeriesModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions<DataType>>({
    title: {
      text: "GDP by State",
    },
    data,
    topology,
    series: [
      {
        type: "map-shape",
        idKey: "name",
        colorKey: "gdp",
        tooltip: {
          renderer: ({ datum }) => ({
            data: [{ label: "GDP", value: numberFormatter.format(datum.gdp) }],
          }),
        },
      },
    ],
    gradientLegend: {
      enabled: true,
      scale: {
        label: {
          fontSize: 9,
          formatter: ({ value }) => `$${Math.floor(+value / 1e6)}T`,
        },
      },
    },
  });

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

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

To colour the shapes based on the magnitude of the data, use colorKey.

{
    series: [
        {
            type: 'map-shape',
            idKey: 'name',
            colorKey: 'gdp',
        },
    ],
}

In this configuration:

colorKey is set to 'gdp', which supplies numerical values for the Colour Scale.

See the Colour Scale page for more details about customising colours, discrete bins, and the Gradient Legend.

Labels 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,
  GradientLegendModule,
  MapShapeSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { DataType, data } from "./data";
import { topology } from "./topology";

const numberFormatter = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  useGrouping: true,
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  GradientLegendModule,
  MapShapeSeriesModule,
  ContextMenuModule,
]);

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions<DataType>>({
    title: {
      text: "GDP by State",
    },
    data,
    topology,
    series: [
      {
        type: "map-shape",
        idKey: "name",
        labelKey: "code",
        colorKey: "gdp",
        tooltip: {
          renderer: ({ datum }) => ({
            data: [
              { label: "GDP", value: numberFormatter.format(datum.gdp) },
              { label: "Code", value: datum.code },
            ],
          }),
        },
      },
    ],
    gradientLegend: {
      enabled: true,
      scale: {
        label: {
          fontSize: 9,
          formatter: ({ value }) => `$${Math.floor(+value / 1e6)}T`,
        },
      },
    },
  });

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

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

{
    series: [
        {
            type: 'map-shape',
            idKey: 'name',
            labelKey: 'code',
        },
    ],
}

In this configuration:

labelKey defines what will appear as the title for each tile.

See Label options for options for handling long labels.

Background Shapes Copy Link

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.

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,
  MapShapeBackgroundSeriesModule,
  MapShapeSeriesModule,
  ModuleRegistry,
} from "ag-charts-enterprise";
import { central, eastern, mountain, pacific } from "./data";
import { topology } from "./topology";

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

const ChartExample = () => {
  const [options, setOptions] = useState<AgChartOptions>({
    title: {
      text: "Timezones Across America",
    },
    topology,
    series: [
      {
        type: "map-shape-background",
      },
      {
        type: "map-shape",
        data: pacific,
        idKey: "name",
        title: "Pacific",
      },
      {
        type: "map-shape",
        data: mountain,
        idKey: "name",
        title: "Mountain",
        visible: false,
      },
      {
        type: "map-shape",
        data: central,
        idKey: "name",
        title: "Central",
        visible: false,
      },
      {
        type: "map-shape",
        data: eastern,
        idKey: "name",
        title: "Eastern",
        visible: false,
      },
    ],
    legend: {
      enabled: true,
    },
  });

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

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

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

Properties available on the AgMapShapeSeriesOptions interface.

type required 'map-shape': Configuration for the Map Shape 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.
colorKey DatumKey: The name of the node key containing the colour value. This value (along with `colorScale` config) will be used to determine the segment colour.
labelKey DatumKey: The key to use to retrieve values from the data to use as labels inside shapes.
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.
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.
colorScale AgColorScale: Configuration for colour scale with fills, domain, and mode.
label AgChartAutoSizedSecondaryLabelOptions: Configuration for the labels shown inside the shape.
padding PixelSize: Distance between the shape edges and the text.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
itemStyler Styler: A callback function for adjusting the styles of a particular Map shape based on the input parameters.
highlight AgMultiSeriesHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
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.

Properties available on the AgMapShapeBackgroundOptions interface.

type required 'map-shape-background': Configuration for the Map Shape Background.
topology GeoJSON: GeoJSON data.
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 - Geographic Areas

Simple Map Shapes Copy Link

Colour Scale Copy Link

Labels Copy Link

Background Shapes Copy Link

API Reference Copy Link