Interactive Maps Made Easy with amCharts: From Setup to Production Dashboard

Why Interactive Maps Are Worth the Effort

A static image of a map answers one question. An interactive map answers every question a user thinks to ask: hover for the underlying number, click to drill into a region, zoom into a country to see provinces, filter by date range, switch from absolute counts to per-capita rates. The same chunk of dashboard real estate works ten times harder once it becomes interactive — and modern users have stopped accepting static maps in any product that calls itself analytics.

The catch has historically been the implementation cost. D3 gives you everything but assumes you want to assemble the wheel yourself; Leaflet is excellent for true geographical tile maps but verbose for choropleths and heatmaps; Google Maps charges you for what should be a static data overlay. amCharts 5 sits in the gap: a high-level API tuned specifically for data visualization rather than navigation, with built-in support for the chart types that fill actual dashboards — choropleths, bubble maps, heatmaps, route maps — and good defaults for the polish details (animations, tooltips, responsive behavior) that take the longest to write by hand.

What amCharts Actually Gives You

amCharts 5 is a TypeScript-first charting library with a dedicated maps module. The map module bundles three things you would otherwise stitch together: a renderer that draws SVG or Canvas paths from GeoJSON, a data-binding layer that ties your business data to geographic features, and a polish layer for tooltips, animations, zoom, pan, and responsive scaling. The headline benefit is that the same library handles everything from a simple country-shaded chart to a real-time bubble map updating from a websocket.

• Country and region-level choropleths — color each shape by your data value
• Bubble and pie-bubble maps — proportional circles at city or region centroids
• Heatmaps — density-based overlays for high-cardinality location data
• Route maps — animated lines between origin and destination pairs
• Drill-down navigation — click a country, zoom into its provinces or states
• Real-time updates — push new values without re-rendering the whole map

The free tier ships with the full library plus a small attribution link in the corner; the commercial license removes it. For internal dashboards the attribution is rarely a blocker; for public-facing product it usually is. Budget for the license before you ship to customers.

Installation and Basic Setup

Two packages cover almost every map use case — the core library and the maps module. The geodata package ships the pre-built GeoJSON files for every country and continent, so you do not have to find and host them yourself.

npm install @amcharts/amcharts5 @amcharts/amcharts5-geodata

amcharts5-geodata is the unsung hero of this stack. It bundles cleaned, optimized GeoJSON for the world, every continent, every country, and most subdivisions (US states, EU regions, Indian states, etc.). Without it you would spend a day hunting down the right shapefile, converting it, and stripping the polygon detail that bloats your bundle. With it, you import a constant and the geometry is ready.

Your First Interactive Map — Thirty Lines

A world map with country-level data shading takes less code than people expect. The pattern below is the minimum viable map: load the world, color it by an arbitrary value, show a tooltip on hover.

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

// Mount on a div with id="chartdiv" in your component.
const root = am5.Root.new('chartdiv');

const chart = root.container.children.push(
  am5map.MapChart.new(root, {
    projection: am5map.geoMercator(),
  })
);

const series = chart.series.push(
  am5map.MapPolygonSeries.new(root, {
    geoJSON: am5geodata_worldLow,
    valueField: 'value',
    calculateAggregates: true,
  })
);

series.mapPolygons.template.setAll({
  tooltipText: '{name}: {value}',
  interactive: true,
  fill: am5.color(0x2a2a35),
  strokeWidth: 0.5,
});

series.set('heatRules', [{
  target: series.mapPolygons.template,
  dataField: 'value',
  min: am5.color(0x3b82f6),
  max: am5.color(0xa78bfa),
  key: 'fill',
}]);

series.data.setAll([
  { id: 'US', value: 320 },
  { id: 'IN', value: 1380 },
  { id: 'BR', value: 215 },
  { id: 'DE', value: 84 },
]);

Read that and you have the full mental model. A Root mounts to your DOM node. A MapChart sits inside it with a projection. A MapPolygonSeries renders shapes from GeoJSON. heatRules tie data values to colors automatically. Data binds by matching the id field in your data array against the id property in the GeoJSON features (ISO 3166-1 alpha-2 country codes here). Everything else — hover behavior, tooltips, responsive scaling — is on by default.

Framework Integration: React, Vue, Angular

amCharts is framework-agnostic but every frontend framework has its own lifecycle concerns. The pattern below is the React idiom — create the chart in useEffect, dispose it in the cleanup. Vue and Angular follow the same pattern with their respective mount/unmount hooks.

// React 18+ with TypeScript.
'use client';
import { useEffect, useRef } from 'react';
import * as am5 from '@amcharts/amcharts5';
import * as am5map from '@amcharts/amcharts5/map';
import am5geodata_worldLow from '@amcharts/amcharts5-geodata/worldLow';

export function WorldMap({ data }: { data: { id: string; value: number }[] }) {
  const rootRef = useRef<am5.Root | null>(null);
  const seriesRef = useRef<am5map.MapPolygonSeries | null>(null);

  useEffect(() => {
    const root = am5.Root.new('worldmap-container');
    const chart = root.container.children.push(
      am5map.MapChart.new(root, { projection: am5map.geoMercator() })
    );
    const series = chart.series.push(
      am5map.MapPolygonSeries.new(root, {
        geoJSON: am5geodata_worldLow,
        valueField: 'value',
        calculateAggregates: true,
      })
    );
    rootRef.current = root;
    seriesRef.current = series;
    return () => root.dispose();
  }, []);

  // Re-bind data without recreating the chart.
  useEffect(() => {
    seriesRef.current?.data.setAll(data);
  }, [data]);

  return <div id="worldmap-container" style={{ width: '100%', height: 500 }} />;
}

Two patterns to internalize. First, root.dispose() in the cleanup function is non-negotiable — without it, React's hot-reload during development leaks chart instances and your dev tab becomes sluggish within minutes. Second, separate the chart creation effect from the data-update effect — recreating the chart on every data change is wasteful and breaks animations.

Production Patterns That Matter

Five patterns that distinguish a working map from a production map:

Drill-Down: Click a Country, Zoom Into Its Regions

One of the features that genuinely separates amCharts from simpler libraries is built-in drill-down navigation. You start with a world map; the user clicks France; the world fades out and France's regions fade in with their own data layer.

import am5geodata_franceLow from '@amcharts/amcharts5-geodata/franceLow';

series.mapPolygons.template.events.on('click', (ev) => {
  const id = ev.target.dataItem?.dataContext?.id;
  if (id === 'FR') {
    // Swap the GeoJSON to France's regions.
    series.set('geoJSON', am5geodata_franceLow);
    series.data.setAll(franceRegionData);
    chart.appear(1000, 100); // re-animate the new map in
  }
});

For full drill-down with a back button, ship a small breadcrumb component that tracks which level the user is on and reverts to the parent GeoJSON on click. amCharts provides hooks for this but does not ship a default breadcrumb — most teams build a simple one in their framework of choice that lives alongside the chart.

Common Pitfalls

Mistakes that show up over and over when teams adopt amCharts maps for the first time:

• Forgetting root.dispose() in cleanup — fastest path to memory leaks during development hot reloads and SPA navigation
• Importing high-detail GeoJSON for charts that only show country-level data — wastes hundreds of KB of bundle size with no visible benefit
• Mixing country names from different sources in the data binding — switch to ISO 3166 codes and the inconsistency disappears
• Server-side rendering the chart — amCharts requires a DOM and window object. Always wrap with dynamic import (Next.js: { ssr: false }) or run in a useEffect
• Setting fixed pixel widths on the container — maps should be fluid; let CSS control the parent size and amCharts will reflow into it on resize
• Forgetting the commercial license for public-facing products — the attribution mark is unobtrusive but it is a license requirement, not a stylistic choice

When to Pick Something Else

amCharts is the right call for data-visualization maps — dashboards, analytics, reports, any view where the geography is a canvas for showing numbers. It is the wrong call for navigation maps (driving directions, store finders, tile-based satellite imagery, search-by-address) — for those, Mapbox GL JS or Leaflet with OpenStreetMap tiles are the standard. The mental test: if you would never zoom past 'see entire region' level, amCharts wins; if your users will pan and zoom to street level, switch to a tile-based map library.

Final Thoughts

Interactive maps used to be the most time-consuming chart type in any dashboard — half a sprint of D3 wrangling for something most users glance at once and move on. amCharts 5 collapses that to about thirty lines of code without giving up the polish that makes maps feel like part of a serious product. Two things matter most in practice: bind data by stable IDs (ISO codes, not names) and dispose the root in your framework's cleanup hook. Get those right and the rest of the API is pleasant to work in. The choropleth is your default; bubble and heatmap series cover most of the cases choropleth does not; drill-down opens a second dimension when a single view is not enough. If you are building a dashboard or analytics product, amCharts maps are the lowest-effort way to add a map view that does not look like a 2015 prototype.

Frequently Asked Questions