Skip to content

A maptalks Layer to render with great d3js library.


Notifications You must be signed in to change notification settings


Repository files navigation


CircleCI NPM Version

A maptalks Layer to render with great d3js library.




  • Install with npm: npm install maptalks.d3.
  • Download from dist directory.
  • Use unpkg CDN:


As a plugin, maptalks.d3 must be loaded after maptalks.js in browsers.

<script type="text/javascript" src=""></script>
<script type="text/javascript" src=""></script>
var d3Layer = new maptalks.D3Layer('d3');
d3Layer.prepareToDraw = function (ctx, projection) {

d3Layer.draw = function (ctx, projection) {
    //drawing the layer


Supported Browsers

IE 9-11, Chrome, Firefox, other modern and mobile browsers.

API Reference

D3Layer is a subclass of maptalks.Layer and inherits all the methods of its parent.


new maptalks.D3Layer(id, options)
  • id String layer id
  • options Object options
    • d3Version Number version of D3: 3 or 4 (4 by default)
    • renderer String renderer of the layer: 'dom' or 'canvas' ('canvas' by default)
    • hideWhenZooming Boolean for dom renderer, whether hide the layer when zooming to improve performance (false by default)
    • container String for dom renderer, specify the container for layer dom elements: 'front' or 'back' ('front' by default)
    • Other options defined in maptalks.Layer

config(key, value)

config layer's options and redraw the layer if necessary

animMarkerLayer.config('animation', 'scale');

Returns this


Whether the layer is rendered by canvas

Returns Boolean


An interface callback method, it is called only once before first drawing and never called again.

It is designed to implement to prepare the context for layer drawing.

The parameters returned by prepareToDraw will be passed to draw method.

  • projection Object map projection object containing project(coord) and unproject(coord) method, returned by map.getProjection()
var d3Layer = new maptalks.D3Layer('d3', { d3Version : 3 });
//Prepare the context parameters for D3Layer's drawing.
//Method prepareToDraw will be called only for once before the first drawing of the layer.
//It can be used to prepare context parameters for draw method
//The parameters returned by prepareToDraw will be passed to draw method.
d3Layer.prepareToDraw = function(context, projection) {
    var colors = [
        'rgba(247,251,255, 0.8)',
        'rgba(222,235,247, 0.8)',
        'rgba(198,219,239, 0.8)',
        'rgba(158,202,225, 0.8)',
        'rgba(107,174,214, 0.8)',
        'rgba(66,146,198, 0.8)',
        'rgba(33,113,181, 0.8)',
        'rgba(8,81,156, 0.8)',
        'rgba(8,48,107, 0.8)'
  var quantize = d3.scale.quantize()
      .domain([0, .15])
      .range(d3.range(9).map(function(i) { return i; }));
  var rateById =;

  //The parameters will be passed to draw method.
  return [rateById, colors, quantize];

Returns this

draw(context, projection, ..params)

The core interface method of D3Layer, implement it to draw the layer on the map.

  • context SVG|Canvas2dContext context for D3 to draw on, possiblly a SVG element (dom renderer) or a canvas 2d context (canvas renderer).
  • projection Object map projection object
  • params Any parameters returns by prepareToDraw method
var d3Layer = new maptalks.D3Layer('d3', { d3Version : 3 });
//context is the canvas context
//projection is the projection object used by d3 to convert geo coordinates to screen points.
d3Layer.draw = function draw(context, projection, rateById, colors, quantize) {
  var layer = this;
  //the d3 path method to draw features on canvas context
  var path = d3.geo.path()
  if (!us) {
    //load data
      .defer(d3.json, "us.json")
      .defer(d3.tsv, "unemployment.tsv", function(d) { rateById.set(, +d.rate); })
      .await(function (error, data) {
        if (error) throw error;
        us = data;
  } else {
    //data is ready and just draw

  function draw() {
    topojson.feature(us, us.objects.counties).features.forEach(function (d) {
      context.fillStyle = colors[quantize(rateById.get(];
    //ask the layer to redraw

Returns this


request layer to draw

Returns this


Get layer's context to draw on, SVG or Canvas2dContext

Returns SVG|Canvas2dContext


Get layer's geo projection method used by D3 internally.

Returns Function


We welcome any kind of contributions including issue reportings, pull requests, documentation corrections, feature requests and any other helps.


The only source file is index.js.

It is written in ES6, transpiled by babel and tested with mocha and expect.js.


  • Install dependencies
$ npm install
  • Watch source changes and generate runnable bundle repeatedly
$ gulp watch
  • Tests
$ npm test
  • Watch source changes and run tests repeatedly
$ gulp tdd
  • Package and generate minified bundles to dist directory
$ gulp minify
  • Lint
$ npm run lint