Introducing d3-shape

Mike Bostock
3 min readDec 3, 2015

Say you’re building a new tool for studying data. What’s the most natural representation for specifying a visualization? A configurable chart? Abstract operators and coordinate systems? Graphical marks and visual encodings?

Each abstraction offers its own advantages. For exploratory visualization, you may favor speed (efficiency) so that you can quickly test different views to discover patterns. For explanatory visualization, as in graphics for a wide audience, you may favor greater control over the output (expressiveness) to communicate insights more effectively.

Regardless of the approach you chose, to implement your tool, you’ll need to actually draw something to the screen. And that means generating geometric shapes that represent data.

How would you draw these shapes?

Some, like bars, are easy: rectangles ripe for the fillRect’ing.

And a straight line isn’t too hard: moveTo, lineTo, repeat.

But what about a smooth curve without cusps or self-intersections?

Or a smooth curve that preserves monotonicity of data?

What about donut slices, perhaps with rounded corners, padding that preserves relative area, and parallel edges between adjacent slices?

Yeesh! Now that’s a challenge.

Enter d3-shape: a small JavaScript library for drawing geometric shapes commonly found in data visualizations, with each shape driven by data through accessor functions. It works with both SVG and Canvas.

How small?

About 28KB minified or 6KB gzipped, including d3-path. That’s only about 1,500 lines of code, so reading the source is highly recommended.

What do you get?

Lines and areas, with a comprehensive set of curves (a.k.a. splines). Pies and arcs (a.k.a. circular and annular sectors); optional rounding and padding. Symbols (a.k.a. markers) for scatterplots.

And there’s more to come, such as layouts for streamgraphs and chord diagrams. A d3-hierarchy module is under development for hierarchical visualizations (e.g., trees, treemaps). Expect additional modules for more specialized applications (geospatial data, force-directed networks, Sankey diagrams, etc.).

Who’s it for?

It’s for authoring new visualization tools, especially in conjunction with frameworks that already have a DOM abstraction and don’t need D3 selections (e.g., React, Angular, Ember). There are quite a few other new modules you might want, such as d3-color, d3-format, d3-time and d3-scale.

It’s also for those looking to contribute to D3 4.0. Want to write a new curve implementation? Or maybe a new smoothing algorithm for noisy data? Read the source, send me a pull request, or read the D3 plugin tutorial and release your own module.

You can also use d3-shape directly to make your own bespoke visualizations. But you may find it easier to use the corresponding classes from D3 3.x (d3.svg.line, d3.svg.area, d3.svg.arc, etc.) until the remaining D3 4.0 modules are released next year.

Happy shaping!



Mike Bostock

Building a better computational medium. Founder @observablehq. Creator #d3js. Former @nytgraphics. Pronounced BOSS-tock.