Highcharts Maps - Highcharts

Highcharts Maps is a comprehensive mapping library for creating interactive geographic visualizations. It supports both traditional choropleth maps with TopoJSON/GeoJSON data and modern tiled web maps with external providers, making it ideal for data-driven geographic visualizations.

Overview

Highcharts Maps provides powerful features for geographic data visualization:

Choropleth Maps: Color-code regions based on data values
Tiled Web Maps: Integration with OpenStreetMap, MapBox, and other providers
Multiple Projections: Built-in support for various map projections
Map Collection: 1,600+ free maps ready to use
GeoJSON/TopoJSON: Standard format support for geographic data
Interactive Features: Zoom, pan, drill-down, and more

Installation

npm install highcharts

ES6 Module Import

import Highcharts from 'highcharts';
import mapModule from 'highcharts/modules/map';

mapModule(Highcharts);

Getting Started

Load the required files

Include Highcharts Maps library in your project:

<script src="https://code.highcharts.com/maps/highmaps.js"></script>

Load map data

Use a map from the Highcharts Map Collection:

const topology = await fetch(
  'https://code.highcharts.com/mapdata/countries/us/us-all.topo.json'
).then(response => response.json());

Create the map

Initialize the map with your data:

Highcharts.mapChart('container', {
  chart: {
    map: topology
  },
  title: {
    text: 'US Population by State'
  },
  series: [{
    data: [
      ['us-ma', 10],
      ['us-wa', 11],
      ['us-ca', 12]
    ],
    mapData: topology,
    joinBy: 'hc-key',
    name: 'Population',
    states: {
      hover: {
        color: '#BADA55'
      }
    },
    dataLabels: {
      enabled: true,
      format: '{point.name}'
    }
  }]
});

Map Types

Choropleth Maps

Color-code geographic regions based on data values - perfect for showing population, elections, or statistical data

Tiled Web Maps

Modern web maps with street tiles from providers like OpenStreetMap and MapBox

Bubble Maps

Display data as sized bubbles on geographic locations

Flow Maps

Visualize movement and connections between locations

Map Collection

Highcharts provides 1,600+ free maps in TopoJSON format, covering:

World maps: Countries, regions, and continents
Country maps: States, provinces, and administrative divisions
Custom regions: EU, Nordic countries, and more

All maps are available at https://code.highcharts.com/mapdata/

// Load a map from the collection
const mapData = await fetch(
  'https://code.highcharts.com/mapdata/countries/gb/gb-all.topo.json'
).then(response => response.json());

Map View and Projection

The MapView class controls how maps are projected and displayed.

Center and Zoom

mapView: {
  center: [-100, 40], // [longitude, latitude]
  zoom: 3,
  projection: {
    name: 'WebMercator'
  }
}

Built-in Projections

Highcharts Maps includes several built-in projections:

WebMercator: Default for tiled web maps
EqualEarth: Equal-area projection
Miller: Compromise cylindrical projection
Orthographic: Globe-like 3D appearance
LambertConformalConic: For mid-latitude regions

mapView: {
  projection: {
    name: 'Orthographic',
    rotation: [60, -30]
  }
}

Insets

Display non-contiguous areas (like Alaska and Hawaii for the US):

mapView: {
  insetOptions: {
    borderColor: '#606060',
    borderWidth: 1
  },
  insets: [{
    id: 'us-hi',
    units: '%',
    borderColor: '#606060',
    borderWidth: 1,
    relativeTo: 'mapBoundingBox',
    field: {
      x: 5,
      y: 80,
      width: 10,
      height: 15
    }
  }]
}

Series Types

Map Series (Choropleth)

The standard map series colors regions based on data values.

series: [{
  type: 'map',
  mapData: topology,
  data: [
    ['us-ny', 100],
    ['us-ca', 200],
    ['us-tx', 150]
  ],
  joinBy: 'hc-key',
  name: 'Population'
}]

MapBubble Series

Display sized bubbles at geographic locations.

series: [{
  type: 'mapbubble',
  name: 'Cities',
  data: [
    { lat: 40.7128, lon: -74.0060, z: 8336817, name: 'New York' },
    { lat: 34.0522, lon: -118.2437, z: 3979576, name: 'Los Angeles' }
  ],
  minSize: 4,
  maxSize: '12%'
}]

MapPoint Series

Display markers at specific locations.

series: [{
  type: 'mappoint',
  name: 'Cities',
  data: [
    { lat: 51.5074, lon: -0.1278, name: 'London' },
    { lat: 48.8566, lon: 2.3522, name: 'Paris' }
  ],
  marker: {
    radius: 5,
    fillColor: 'red'
  }
}]

MapLine Series

Draw lines between locations (routes, borders).

series: [{
  type: 'mapline',
  name: 'Flight Route',
  data: [{
    geometry: {
      type: 'LineString',
      coordinates: [
        [-74.0060, 40.7128], // New York
        [-0.1278, 51.5074]   // London
      ]
    }
  }],
  color: '#0066cc',
  lineWidth: 2
}]

FlowMap Series

Visualize movement and migration between locations.

series: [{
  type: 'flowmap',
  data: [
    {
      from: 'New York',
      to: 'London',
      weight: 1000
    },
    {
      from: 'London',
      to: 'Paris',
      weight: 500
    }
  ],
  lineWidth: 2
}]

Tiled Web Maps

Integrate modern tiled web maps from providers like OpenStreetMap.

Highcharts.mapChart('container', {
  chart: {
    map: 'custom/world'
  },
  mapView: {
    center: [10, 59],
    zoom: 10
  },
  series: [{
    type: 'tiledwebmap',
    name: 'Basemap Tiles',
    provider: {
      type: 'OpenStreetMap'
    },
    showInLegend: false
  }, {
    type: 'mappoint',
    name: 'Cities',
    data: pointData
  }]
});

Supported Providers

OpenStreetMap
Stamen (Terrain, Toner, Watercolor)
Thunderforest
Esri (WorldStreetMap, WorldTopoMap, WorldImagery)
USGS (USImagery, USTopo)

Color Axis

Create color scales for choropleth maps.

colorAxis: {
  min: 0,
  max: 1000,
  stops: [
    [0, '#F1EEF6'],
    [0.5, '#900037'],
    [1, '#500007']
  ],
  labels: {
    format: '{value}'
  }
}

Data Classes

Define discrete color ranges:

colorAxis: {
  dataClasses: [
    { from: 0, to: 100, color: '#F1EEF6', name: 'Low' },
    { from: 100, to: 500, color: '#900037', name: 'Medium' },
    { from: 500, color: '#500007', name: 'High' }
  ]
}

Enable interactive zoom and pan controls.

mapNavigation: {
  enabled: true,
  buttonOptions: {
    verticalAlign: 'bottom'
  },
  enableMouseWheelZoom: true,
  enableTouchZoom: true,
  enableDoubleClickZoom: true,
  enableDoubleClickZoomTo: true
}

Advanced Examples

Map Drill-Down

Click regions to drill down to more detailed maps:

series: [{
  data: countryData,
  mapData: worldMap,
  joinBy: ['iso-a2', 'code'],
  name: 'Countries',
  states: {
    hover: {
      color: '#a4edba'
    }
  },
  point: {
    events: {
      click: function() {
        // Load detailed map for this country
        const drilldown = this.drilldown;
        if (drilldown) {
          loadDetailedMap(drilldown);
        }
      }
    }
  }
}]

Marker Clusters

Automatically cluster nearby points:

<script src="https://code.highcharts.com/maps/modules/marker-clusters.js"></script>

plotOptions: {
  mappoint: {
    cluster: {
      enabled: true,
      allowOverlap: false,
      animation: {
        duration: 450
      },
      layoutAlgorithm: {
        type: 'grid',
        gridSize: 50
      }
    }
  }
}

GeoHeatmap

Visualize density with geographic heatmaps:

series: [{
  type: 'geoheatmap',
  data: [
    { lat: 40.7128, lon: -74.0060, value: 100 },
    { lat: 34.0522, lon: -118.2437, value: 80 }
  ],
  colsize: 5, // degrees
  rowsize: 5,
  nullColor: 'transparent'
}]

Custom Maps

Create maps from your own geographic data:

Prepare GeoJSON/TopoJSON

Use GIS software to export your geographic data as GeoJSON or TopoJSON

Convert to TopoJSON (recommended)

TopoJSON is more compact than GeoJSON:

geo2topo input.geojson > output.topojson

Load in Highcharts

const customMap = await fetch('path/to/custom-map.topojson')
  .then(response => response.json());

Highcharts.mapChart('container', {
  chart: {
    map: customMap
  },
  series: [{
    data: yourData
  }]
});

Joining Data to Maps

Connect your data to map regions using the joinBy option:

series: [{
  mapData: topology,
  data: [
    ['us-ny', 100],
    ['us-ca', 200]
  ],
  joinBy: 'hc-key', // Join by the 'hc-key' property
  name: 'Random data'
}]

Alternative methods:

// Join by different properties
joinBy: ['iso-a2', 'code'] // [mapProperty, dataProperty]

// Or include geometry directly in data
data: [{
  geometry: { /* GeoJSON geometry */ },
  value: 100
}]

Performance Tips

Optimize Map Performance

Use TopoJSON instead of GeoJSON (smaller file size)
Simplify complex geometries before importing
Use marker clusters for large point datasets
Enable data grouping for time-series map data
Limit the number of regions displayed at once

API Reference

Complete Highcharts Maps API documentation

Map Collection

1,600+ free maps in TopoJSON format

Live Demos

Interactive examples and demos

Map Editor

Convert SVG files to Highcharts maps

Next Steps

Explore the Map Collection to find pre-built maps
Learn about Map Projections for different visualizations
Try Tiled Web Maps for modern street map backgrounds
Implement Drill-Down for interactive geographic exploration

Getting Started

Core Concepts

Chart Types

Features

Advanced

Products

​Overview

​Installation

​ES6 Module Import

​Getting Started

​Map Types

Choropleth Maps

Tiled Web Maps

Bubble Maps

Flow Maps

​Map Collection

​Map View and Projection

​Center and Zoom

​Built-in Projections

​Insets

​Series Types

​Map Series (Choropleth)

​MapBubble Series

​MapPoint Series

​MapLine Series

​FlowMap Series

​Tiled Web Maps

​Supported Providers

​Color Axis

​Data Classes

​Map Navigation

​Advanced Examples

​Map Drill-Down

​Marker Clusters

​GeoHeatmap

​Custom Maps

​Joining Data to Maps

​Performance Tips

Optimize Map Performance

​Related Resources

API Reference

Map Collection

Live Demos

Map Editor

​Next Steps

Build docs developers (and LLMs) love

Overview

Installation

ES6 Module Import

Getting Started

Map Types

Map Collection

Map View and Projection

Center and Zoom

Built-in Projections

Insets

Series Types

Map Series (Choropleth)

MapBubble Series

MapPoint Series

MapLine Series

FlowMap Series

Tiled Web Maps

Supported Providers

Color Axis

Data Classes

Map Navigation

Advanced Examples

Map Drill-Down

Marker Clusters

GeoHeatmap

Custom Maps

Joining Data to Maps

Performance Tips

Related Resources

Next Steps