The Hitchhiker’s Guide to d3.js

The landscape for learning d3 is rich, vast and sometimes perilous. You may be intimidated by the long list of functions in d3’s API documentation or paralyzed by choice reviewing the dozens of tutorials on the home page. There are over 20,000+ d3 examples you could learn from, but you never know how approachable any given one will be.

If all you need is a quick bar or line chart, maybe this article isn’t for you, there are plenty of charting libraries out there for that. If you’re into books, check out Interactive Data Visualization for the Web by Scott Murray as a great place to start. D3.js in Action by Elijah Meeks is a comprehensive way to go much deeper into some regions of the API.

This guide is meant to prepare you mentally as well as give you some fruitful directions to pursue. There is a lot to learn besides the d3.js API, both technical knowledge around web standards like HTML, SVG, CSS and JavaScript as well as communication concepts and data visualization principles. Chances are you know something about some of those things, so this guide will attempt to give you good starting points for the things you want to learn more about.

Communicate Complex Concepts

Before we dive into data visualization principles and technical skills, lets take a second to be aspirational. There are some amazing examples of what’s possible in this medium, whether its a New York Times article, r2d3, distill.pub, datasketch|es, polygraph, or ncase. Be sure to leave a comment with any inspirations I didn’t list here!

Don’t just look to others though, one of the most important things you can do is set an aspiration for yourself. I found out from interviewing some of the top data visualization practitioners using d3.js that one of the best ways to learn is to set your sights something you really want to build and figure out what you need to build it.

Visual Representations

D3 does not introduce a new visual representation. Unlike Processing, Raphaël, or Protovis, D3’s vocabulary of graphical marks comes directly from web standards: HTML, SVG, and CSS
 — http://d3js.org

Charts are just rectangles with shapes inside of them. There are a handful of configurations of those shapes we recognize as common charts or graphs. What d3 provides is a way to define your own visual representations by manipulating graphical marks or creating your own shapes. It makes it easy to add interactions to visuals and declare how your visuals behave. You are here to learn how to express things that aren’t possible to express in any other medium.

If you want to learn about some of the principles behind the different kinds of marks and graphical representations people use, you can’t go wrong exploring the Grammar of Graphics.

Don’t worry though, there are a ton of creative things you can do with just circles, rectangles and some careful positioning. Start simple, always try to get something to show up on the screen and build up from there.

On the web

One of the reasons you want to use d3.js is so you can share your work instantly with anyone who uses a web browser (at least half of the people on Earth!). That means you need to have at least a passing understanding of the medium you’ll be working in, which is HTML5. So before you even start calling d3 API functions you’ll need some basics in SVG, HMTL and CSS. You’ll probably also want to learn some Canvas if you want to be serious about rendering a lot of data (don’t worry, its actually kind of easier to learn than SVG). I recommend this is a great intermediate tutorial on using d3 with Canvas after you are comfortable with the basics of both.

For SVG I recommend starting with this short but sweet SVG primer by Scott Murray. Play around with manually creating SVG elements and seeing how they work. Use a tool like BlockBuilder to quickly get started without setting up any kind of development environment. You may want to refer to the MDN reference site for SVG. Once you’ve mastered the basics, check out SVG beyond mere shapes by Nadieh Brehmer.

You don’t have to use SVG to make your visualization, it’s relatively common to manipulate HTML elements like <div> tags with d3. You will need to be familiar with CSS positioning to make it work well. You can even mix HTML, SVG and Canvas all at once!

It can be a bit overwhelming to figure out which rendering system you should use, and even how to use any one of them. I’m going to reiterate the importance of knowing basic HTML, CSS, SVG (and a little Canvas) before getting started with d3.js!

Getting started with d3.js

How do you build up your visualization from first principles? Piece by piece and a whole lot of utility functions. As you’ve probably seen, d3’s API is massive, so lets call out a few of the utilities that will be particularly helpful early on.

d3-scale

Some of the most fundamental tools in the d3 tool belt are scales. Start with the Introducing d3-scale post by Mike Bostock to get an overview of what they are and how to use them. No matter what kind of visualization you do, you will likely use at least one kind of scale to make it happen.

d3-shape

SVG paths are pretty intense (see this thorough overview), so d3-shape includes functions that will make them easier to create and manipulate for some use cases. Read Mike’s Introducing d3-shape article to get an overview of what it offers and how to get started using them. d3-shape can also help you render things like lines, areas and arbitrary paths to Canvas with just one extra line of code!

d3-selection

One of the hardest parts of d3 to learn is the selection system, also referred to as the General Update Pattern. It took me months of banging my head against my desk to internalize it, but don’t let that scare you! You don’t actually need to be a master of selections to get a ton of cool stuff done. When you are ready to give it a shot, you can start with the d3-selections README and be sure to click on the links like Thinking in Joins.

d3-collection

Manipulating data is an incredibly important part of visualizing it. This can often be the hardest part to do depending on how good your data is and how well you understand it. Having more tools that make working with the data by reshaping it, slicing and dicing or aggregating it can really help. To this end I recommend getting familiar with d3-collection, particularly the nest function.

d3-hierarchy

Continuing the theme of working with data, the key part to many visualizations is laying out your visual representations based on your data’s structure. Some common functions for helping you do this are found in d3-hierarchy for making things like trees, treemaps or circle packs.

d3-zoom

A common interaction behavior you may want to add to your visualization is zooming. Mike has a series of examples that show various ways of adding zoom to your visualization with d3-zoom. Check out zoom’s close cousin d3-drag for some additional interaction help!

d3-force

One of d3’s capabilities that inspires a lot of people is the force layout. It’s pretty easy to use but definitely difficult to master. Just don’t let it pull you to the dark side! See d3-force for more details.

Search!

One final tip you can use for any API function is to use BlockBuilder’s search capability. You can also limit your searches to examples that use d3 v4!

Community

Connect with like-minded folks! We have a vibrant online community in the d3.js slack channel. Find a meetup near you, the SF Bay Area has one of the biggest groups, but you can probably find some groups near you. If you’re really dedicated, come to the annual d3.unconf held in SF every fall!

Many thanks to Erik Hazzard for editing and helping shape this post. Thanks to Kai Chang for his suggestions in this post but more so for helping shape the d3 community. Thanks to #teaching-d3 in the d3js Slack, especially Sebastian and John for their feedback. Of course Infinite thanks to Mike Bostock for creating the playground we all get to work in!