How To: Draw a World Map with D3 in just 16 lines

D3 - which stands for Data-Driven Documents is an amazing data visualization library. It's pretty that you can draw a map of the world, with all the countries in it in just 16 lines of code.

import { select, json, geoPath, geoNaturalEarth1 } from 'd3';import { feature } from 'topojson';const svg = select('svg');const projection = geoNaturalEarth1();const pathGenerator = geoPath().projection(projection);svg.append('path')    .attr('class', 'sphere')    .attr('d', pathGenerator({type: 'Sphere'}));json('https://unpkg.com/[email protected]/world/110m.json')  .then(data => {    const countries = feature(data, data.objects.countries);    svg.selectAll('path').data(countries.features)      .enter().append('path')        .attr('class', 'country')        .attr('d', pathGenerator);  });

Okay, there's an index.html file with another 12 lines of code, and a CSS file with another 10, but still. What strange incantation/sorcery is this?! What's exactly going on here? How do these lines finesse an entire World map?!

FYI, this code comes from a free 13-hour video course that found on FreeCodeCamp. This post is an attempt to explain how to draw a map of the world using D3js.

Before we jump into the code, read up on this D3 concept known as the data join, along with pre-reqs such as CSS and loading data. For highest fidelity, watch this 17-minute video and come back to get a line-by-line breakdown here.

Line 1:

import { select, json, geoPath, geoNaturalEarth1 } from 'd3';

The D3 library was loaded in the index.html file using a script tag on line 6. We're importing four D3 modules using ES6 module syntax here.

select This d3 module selects the first DOM element that matches the specified selector string.
json A function from the d3-fetch module that fetches the JSON file at the specified input URL.
geoPath This module converts the data path into an SVG path. A string that we can use on SVG paths.
geoNaturalEarth1 A geographic map projection style.

Line 2:

import { feature } from 'topojson';

TopoJSON is an extension of GeoJSON (a format designed for representing geographical features using JSON (JavaScript Object Notation)) that encodes topology.

Topojson.feature is the function that we need to convert our TopoJSON into geoJSON. In our code we can say import {feature} from topojson and in line 15, we invoke feature, passing in as the first argument the data and the second argument is the countries.

Line 3:

const svg = select('svg');

The const declaration creates a read-only reference to a value. We're calling the D3 module select on the SVG element which was declared in the index.html file, and assigning it to a named constant called svg.

Line 4,5:

const projection = geoNaturalEarth1();const pathGenerator = geoPath().projection(projection);

We make use of the geoNaturalEarth1 projection style that we imported in line 1. We assign it to a named constant, which is passed on to the geoPath.projection function on line 5. geoPath is a path generator that generates an SVG path data string here.

Line 6-8:

svg.append('path')    .attr('class', 'sphere')    .attr('d', pathGenerator({type: 'Sphere'}));

These three lines draw a sphere around the World map. We draw a new path by appending the SVG on line 6, and on this path, on line 9, we set the d attribute to be our pathGenerator, and pass in an object where the type is 'Sphere'.

Line 9-15

json('https://unpkg.com/[email protected]/world/110m.json')  .then(data => {    const countries = feature(data, data.objects.countries);    svg.selectAll('path').data(countries.features)      .enter().append('path')        .attr('class', 'country')        .attr('d', pathGenerator);  });

We fetch the shape data of the countries from the world-atlas TopoJSON file, and then pass a function as input, the data. We invoke topojson.feature, passing in as the first argument the data, and the second argument is the countries(data.object.countries).

We then draw a path for each country in countries.features using the selection.enter() update pattern, and set its class as 'country' (for CSS styling purposes). The outline of the country is defined by the d attribute, which defines the path to be drawn.