Implementing Map Drill-Down in ECharts: A Step-by-Step Guide

1. Introduction

Among the many ECharts chart types, map visualizations are often the most complex, especially when implementing hierarchical drill‑down functionality. This guide shows how to build a full map drill‑down feature that lets users click a region to view lower‑level geographic data.

2. What Is Map Drill‑Down?

Map drill‑down (Drill‑down) is an advanced interaction that lets users explore increasingly detailed geographic layers, such as moving from a province map to city and then district maps, enhancing data analysis and user experience.

3. How to Implement Map Drill‑Down in ECharts

The process can be broken into four steps:

Prepare map data

Initialize the ECharts map

Set up a click‑event listener

Render the drill‑down map

First, instantiate a basic China map as the foundation. The article references a previous post on creating a compliant China map.

3.1 Prepare Map Data

Obtain multi‑level GeoJSON files (country, province, city, etc.) from sources such as Alibaba Cloud DataV. Ensure the data conforms to ECharts’ format.

Example API for online GeoJSON (for testing only): https://geo.datav.aliyun.com/areas_v3/bound/geojson?code={adcode}_full

3.2 Initialize the ECharts Map

Register the map and set the basic option. Example code:

const myChart = echarts.init(document.getElementById("main"));
function setOption(name, data) {
  const option = {
    geo: {
      map: name,
      roam: true,
    },
    series: [{
      type: "map",
      map: name,
      geoIndex: 0,
      roam: true,
      data: data,
    }],
  };
  myChart.setOption(option, true);
}
const data = chinaGeoJson; // prepared GeoJSON
setOption("china", data);

3.3 Set Up Click Event Listener

Capture the region’s adcode when a user clicks:

myChart.on("click", function (params) {
  if (params.data) {
    const { adcode, name, level } = params.data;
    // use adcode to fetch next level data
  }
});

3.4 Render the Sub‑Region Map

Fetch the child GeoJSON using the adcode and render it:

// Fetch GeoJSON by adcode
function getJSON(adcode, callback) {
  $.getJSON(`https://geo.datav.aliyun.com/areas_v3/bound/geojson?code=${adcode}_full`, function (data) {
    callback(data);
  });
}
// Example: load cities of Shandong province
getJSON("370000", function (data) {
  console.log("Shandong sub‑regions:", data);
});

After obtaining the data, register the new map and update the chart:

function renderChart(name, data) {
  echarts.registerMap(name, data);
  const mapdata = data.features.map(item => item.properties);
  setOption(name, mapdata);
}
getJSON("370000", function (data) {
  renderChart("Shandong", data);
});

4. Enhancing Interaction

Handle edge cases such as reaching the deepest level or navigating back:

// Detect bottom level and alert
myChart.on("click", function (params) {
  if (params.data) {
    const { adcode, name, level } = params.data;
    if (level === "district") {
      alert("No further map available!");
      initChinaMap();
      return;
    }
    getJSON({ name, adcode }, function (data) {
      renderChart(name, data);
    });
  }
});

Maintain a stack of visited maps to enable a back button:

let mapList = [];
function setBackbtn({ name, adcode }) {
  if (adcode === 100000) {
    $("#back").hide();
  } else {
    $("#back").show();
  }
}
function goBack() {
  if (mapList.length >= 2) {
    const { name, adcode } = mapList[mapList.length - 2];
    mapList.splice(-2, 2);
    getJSON({ name, adcode }, function (data) {
      renderChart(name, data);
    });
  }
}

5. Custom Tooltip

Show adcode, name, and level on hover:

option = {
  tooltip: {
    formatter: function (params) {
      const { adcode, name, level } = params.data;
      return `adcode: ${adcode}
name: ${name}
level: ${level}`;
    }
  }
};

6. Summary

The guide provides a clear workflow for implementing map drill‑down in ECharts, covering data acquisition, chart setup, event handling, navigation, and tooltip customization. While the core logic is covered, further enhancements such as color mapping, data labeling, and performance tuning may be added as needed.