MapChart

Overview

MapChart is the main class for creating map visualizations in amCharts 5. It extends SerialChart and provides functionality for displaying geographic data with various projections, zoom controls, and pan/zoom interactions.

Creating a MapChart

import * as am5 from "@amcharts/amcharts5";
import * as am5map from "@amcharts/amcharts5/map";
import { geoMercator } from "@amcharts/amcharts5/map";

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: geoMercator(),
    panX: "translateX",
    panY: "translateY",
    wheelY: "zoom"
  })
);

Settings

Projection

projection

GeoProjection

A projection to use when plotting the map. See the Projections page for available options.

import { geoMercator } from "@amcharts/amcharts5/map";

chart.set("projection", geoMercator());

Zoom and Position

zoomLevel

number

Current zoom level of the map.

chart.set("zoomLevel", 2);

minZoomLevel

number

default:"1"

Lowest zoom level the map is allowed to zoom out to.

maxZoomLevel

number

default:"32"

Highest zoom level the map is allowed to zoom in to.

zoomStep

number

default:"2"

Increment zoom level by this value when user zooms in via ZoomControl or API.

translateX

number

Current x position of the map.

translateY

number

Current y position of the map.

Rotation

rotationX

number

Horizontal centering of the map. Use with projections that support rotation.See Centering the map for more info.

rotationY

number

Vertical centering of the map. Use with projections that support rotation.

rotationZ

number

Depth centering of the map. Use with projections that support rotation.

Pan Behavior

panX

'none' | 'rotateX' | 'translateX'

default:"translateX"

Defines what happens when map is dragged horizontally.

"none" - No panning
"rotateX" - Rotate the globe
"translateX" - Translate the map

See Panning for more info.

panY

'none' | 'rotateY' | 'translateY'

default:"translateY"

Defines what happens when map is dragged vertically.

maxPanOut

number

default:"0.4"

How much of a map can go outside the viewport (0-1 where 0.4 = 40%).See Panning outside viewport for more info.

Wheel Behavior

wheelY

'none' | 'zoom' | 'rotateX' | 'rotateY'

default:"zoom"

Defines what happens when mouse wheel is turned.See Mouse wheel behavior for more info.

wheelX

'none' | 'zoom' | 'rotateX' | 'rotateY'

default:"none"

Defines what happens when horizontal mouse wheel is turned (only some mice support this).

wheelSensitivity

number

default:"1"

Sensitivity of mouse wheel. This setting is ignored when wheelX or wheelY is set to “zoom”.

wheelDuration

number

Duration of mouse-wheel action animation in milliseconds. This setting is ignored when wheelX or wheelY is set to “zoom”.

wheelEasing

(t: Time) => Time

An easing function to use for mouse wheel action animations. This setting is ignored when wheelX or wheelY is set to “zoom”.See Easing functions for more info.

Pinch Zoom

pinchZoom

boolean

default:"true"

Enables pinch-zooming of the map on multi-touch devices.See Pinch zoom for more info.

Animation

animationDuration

number

Duration of zoom/pan animations in milliseconds.

animationEasing

(t: Time) => Time

An easing function to use for zoom/pan animations.See Easing functions for more info.

Home Position

homeZoomLevel

number

Initial/home zoom level.See Initial position and zoom for more info.

homeRotationX

number

Initial/home rotationX.

homeRotationY

number

Initial/home rotationY.

homeGeoPoint

IGeoPoint

Initial coordinates to center map on load or goHome() call.

chart.set("homeGeoPoint", { longitude: -73.9352, latitude: 40.7306 });

centerMapOnZoomOut

boolean

default:"true"

If true, the map will automatically center itself (or go to homeGeoPoint if set) when fully zoomed out.If false, zoom out will be centered around the mouse cursor (when zooming using wheel), or current map position.

Zoom Control

zoomControl

ZoomControl

A ZoomControl instance for zoom in/out buttons.See Zoom control for more info.

const zoomControl = am5map.ZoomControl.new(root, {});
chart.set("zoomControl", zoomControl);

Methods

Zoom Methods

zoomIn()

Animation<number> | undefined

Zooms the map in by the zoomStep amount.

chart.zoomIn();

zoomOut()

Animation<number> | undefined

Zooms the map out by the zoomStep amount.

chart.zoomOut();

zoomToPoint(point, level, center?, duration?)

Animation<number> | undefined

Zooms the map to a specific screen point.

Show Parameters

point

IPoint

required

Screen point coordinates { x: number, y: number }

level

number

required

Target zoom level

center

boolean

Whether to center the map on the point

duration

number

Animation duration in milliseconds

chart.zoomToPoint({ x: 100, y: 100 }, 4, true, 1000);

zoomToGeoPoint(geoPoint, level, center?, duration?, rotationX?, rotationY?)

Animation<number> | undefined

Zooms the map to a specific geographical point.

Show Parameters

geoPoint

IGeoPoint

required

Geographical coordinates { longitude: number, latitude: number }

level

number

required

Target zoom level

center

boolean

Whether to center the map on the point

duration

number

Animation duration in milliseconds

rotationX

number

X rotation of the map at the end of zoom

rotationY

number

Y rotation of the map at the end of zoom

chart.zoomToGeoPoint(
  { longitude: -73.9352, latitude: 40.7306 },
  4,
  true,
  1000
);

zoomToGeoBounds(geoBounds, duration?, rotationX?, rotationY?)

Animation<number> | undefined

Zooms the map to fit geographical bounds.

Show Parameters

geoBounds

object

required

Geographical bounds with left, right, top, bottom properties

duration

number

Animation duration in milliseconds

rotationX

number

X rotation of the map at the end of zoom

rotationY

number

Y rotation of the map at the end of zoom

chart.zoomToGeoBounds({
  left: -130,
  right: -60,
  top: 50,
  bottom: 20
});

goHome(duration?)

void

Repositions the map to the “home” zoom level and center coordinates.

Show Parameters

duration

number

Animation duration in milliseconds

See Resetting position/level for more info.

chart.goHome(1000);

Rotation Methods

rotate(rotationX?, rotationY?, duration?)

void

Rotates the map (for projections that support rotation).

Show Parameters

rotationX

number

Target X rotation

rotationY

number

Target Y rotation

duration

number

Animation duration in milliseconds

chart.rotate(-73.9352, -40.7306, 1000);

animateProjection(target, targetRaw, duration?, easing?, sourceRaw?)

void

Animates the map projection transition from the current projection to the target projection.Since d3-geo does not expose raw projection functions on projection instances, you must pass both the target GeoProjection and its corresponding GeoRawProjection. On the first call you must also pass sourceRaw so the method knows the current projection’s raw function.

Show Parameters

target

GeoProjection

required

Target projection (e.g., geoOrthographic())

targetRaw

GeoRawProjection

required

Raw projection function (e.g., geoOrthographicRaw)

duration

number

Duration in milliseconds (default: animationDuration)

easing

(t: Time) => Time

Easing function (default: animationEasing)

sourceRaw

GeoRawProjection

Raw function of the current projection (needed on first call)

import { geoOrthographic, geoOrthographicRaw } from "d3-geo";

chart.animateProjection(
  geoOrthographic(),
  geoOrthographicRaw,
  2000
);

Coordinate Conversion

convert(point, rotationX?, rotationY?)

IPoint

Converts latitude/longitude to screen coordinates (X and Y).

Show Parameters

point

IGeoPoint

required

Geographical coordinates

rotationX

number

X rotation of the map if different from current

rotationY

number

Y rotation of the map if different from current

const screenPoint = chart.convert({ longitude: -73.9352, latitude: 40.7306 });
console.log(screenPoint); // { x: 150, y: 200 }

invert(point)

IGeoPoint

Converts screen coordinates (X and Y) to latitude and longitude.

Show Parameters

point

IPoint

required

Screen coordinates

const geoPoint = chart.invert({ x: 150, y: 200 });
console.log(geoPoint); // { longitude: -73.9352, latitude: 40.7306 }

Information Methods

geoPoint()

IGeoPoint

Returns the geoPoint of the current zoom position.You can use this to restore zoom position: chart.zoomToGeoPoint(geoPoint, zoomLevel, true)

const currentGeoPoint = chart.geoPoint();

geoCentroid()

IGeoPoint

Returns coordinates to the geographical center of the map.

const centroid = chart.geoCentroid();

geoBounds()

object

Returns geographical bounds of the map.Returns an object with left, right, top, bottom properties.

const bounds = chart.geoBounds();
console.log(bounds); // { left: -180, right: 180, top: 85, bottom: -85 }

homeGeoPoint()

IGeoPoint

Returns geographical coordinates for calculated or manual center of the map.

const homePoint = chart.homeGeoPoint();

getArea(dataItem)

number

Returns area of a MapPolygon in square pixels.

Show Parameters

dataItem

DataItem<IMapPolygonSeriesDataItem>

required

The polygon data item to measure

const area = chart.getArea(polygonDataItem);

Events

geoboundschanged

{}

Invoked when geo bounds of the map change, usually after map is initialized.

chart.events.on("geoboundschanged", (ev) => {
  console.log("Bounds changed", chart.geoBounds());
});

Example

import * as am5 from "@amcharts/amcharts5";
import * as am5map from "@amcharts/amcharts5/map";
import am5geodata_worldLow from "@amcharts/amcharts5-geodata/worldLow";

const root = am5.Root.new("chartdiv");

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
    panX: "translateX",
    panY: "translateY",
    wheelY: "zoom",
    homeZoomLevel: 1.2,
    homeGeoPoint: { longitude: 10, latitude: 52 }
  })
);

const polygonSeries = chart.series.push(
  am5map.MapPolygonSeries.new(root, {
    geoJSON: am5geodata_worldLow
  })
);

const zoomControl = chart.set("zoomControl",
  am5map.ZoomControl.new(root, {})
);

Core

Shapes

Controls

XY Charts

Map Charts

Stock Charts

Hierarchy Charts

Utilities

Overview

Creating a MapChart

Settings

Projection

Zoom and Position

Rotation

Pan Behavior

Wheel Behavior

Pinch Zoom

Animation

Home Position

Zoom Control

Methods

Zoom Methods

Rotation Methods

Coordinate Conversion

Information Methods

Events

Example

Build docs developers (and LLMs) love

Core

Shapes

Controls

XY Charts

Map Charts

Stock Charts

Hierarchy Charts

Utilities

​Overview

​Creating a MapChart

​Settings

​Projection

​Zoom and Position

​Rotation

​Pan Behavior

​Wheel Behavior

​Pinch Zoom

​Animation

​Home Position

​Zoom Control

​Methods

​Zoom Methods

​Rotation Methods

​Coordinate Conversion

​Information Methods

​Events

​Example

Build docs developers (and LLMs) love

Overview

Creating a MapChart

Settings

Projection

Zoom and Position

Rotation

Pan Behavior

Wheel Behavior

Pinch Zoom

Animation

Home Position

Zoom Control

Methods

Zoom Methods

Rotation Methods

Coordinate Conversion

Information Methods

Events

Example