D3 is built on top of several common web standards. Don’t worry if you don’t know all the nitty-gritty details of these standards, you can pick this stuff up pretty quickly.

HTML

HTML (HyperText Markup Language) is a text format that most web pages are written in. HTML uses a standard set of tags to define the different structural components of a webpage: <h1>, <h2> tags define headers, <p> tags define paragraphs, <ol> and <ul> are orderered and unordered lists. Browsers have common ways to display these tags, so lists show up like lists, and headers like headers.

The <div> and <span> tags are special because browers don’t apply default styles to them, so HTML authors can use them to define custom groups.

The basic outline of an HTML page is something like this:

<!DOCTYPE html>
<html>
  <head>
    <title>TITLE GOES HERE</title>
  </head>
  <body>
    MAIN CONTENT GOES HERE
  </body>
</html>

CSS

CSS (Cascading Stylesheets) is a language for styling HTML pages.

CSS styles (also know as selectors) are typically applied to HTML tags based on their name, class, or ID.

Here are some simple CSS rules and how they apply.

<div>
  <p>Normal paragraph</p>

  <p class="red">Red paragraph</p>
</div>

<ol>
  <li id="some-id">Unique element</li>
  <li>Another list element</li>
  <li>
    <p>Paragraph inside list element</p>
    <p>Second paragraph</p>
  </li>
</ol>

    
/* Applied to all <p> tags */
p {
  color: blue;
}

/* Applied to all tags with the class "red" */
.red {
  background: red;
}

/* Applied to the tag with the id "some-id" */
#some-id {
  font-style: italic;
}

/* Applied only to <p> tags that are inside <li> tags */
li p {
  color: #0C0;
}

The DOM

When a browser displays an HTML page, it creates an interactive object graph from the tag hierarchy. This object graph is called the Document Object Model, or DOM.

The standard DOM API is somewhat verbose, so many libraries like jQuery and D3 provide some syntactic sugar that borrows from CSS notation.

Here are some examples of accessing the DOM programatically.

<div>
  <p>Normal paragraph</p>

  <p class="red">Red paragraph</p>
</div>

<ol>
  <li id="some-id">Unique element</li>
  <li>Another list element</li>
  <li>
    <p>Paragraph inside list element</p>
    <p>Second paragraph</p>
  </li>
</ol>

    
// DOM API
document.getElementById('some-id');
// <li id="some-id">Unique element</li>
document.getElementsByTagName('p').length;
// 4
var reds = document.getElementsByClassName('red');
// [<p class="red">Red paragraph</p>]
reds[0].innerText
// "Red paragraph"
    
// D3 Selection API
d3.select('p').size(); // select() only finds one
// 1
d3.selectAll('p').size(); // selectAll() finds all
// 4
var reds = d3.selectAll('.red');
// [ > Array[1] ]
reds.text();
// "Red paragraph"

The DOM also handles tracking elements as they are rendered, as well as events like mouse movement. You can attach listeners to these events to add various levels of interactivity to your page.

Here are some examples of adding listeners to the click, mouseover and mouseleave events. D3 has some nice helper methods for working with events as well.

<h1 id="click-me">
  Click on me!
</h1>

<p class="hover-me">
  Hover over me!
</p>

<p class="hover-me">
  OK now hover over here!
</p>

<p class="hover-me">
  Hover here too!
</p>
    
// DOM API
var clickMe = document.getElementById('click-me');
clickMe.onclick = function() {
  if (this.style.backgroundColor) {
    this.style.backgroundColor = '';
  } else {
    this.style.backgroundColor = 'red';
  }
}

// D3 Selection API. Note: it attaches the
// callbacks to each element in the selection
d3.selectAll('.hover-me')
  .on('mouseover', function() {
    this.style.backgroundColor = 'yellow';
  })
  .on('mouseleave', function() {
    this.style.backgroundColor = '';
  });
Note: In the D3 examples, the methods on the selection can chain (that is, they return themselves, so we can group them visually).

SVG

SVG (Scalable Vector Graphics) is an XML format used for drawing. You can think of SVG in a lot of the same terms as the DOM – there are elements with parents and children and attributes, and you can respond to the same mouse/touch events.

Even CSS styles and selectors can apply to SVG elements. The CSS attribute names for SVG come from the SVG definition, so they are sometimes different from their HTML brethren. (For example, to change the background color of a div to red you would select it then set background-color: red but to get the same effect on an SVG rectangle you would instead use the attribute fill: red since an SVG rect doesn’t respond to background-color for styling.)

SVG defines tags for lots of basic shapes, like <rect> and <circle> and <line>.

<svg width="300" height="180">
  <circle cx="30"  cy="50" r="25" />
  <circle cx="90"  cy="50" r="25" class="red" />
  <circle cx="150" cy="50" r="25" class="fancy" />

  <rect x="10"  y="80" width="40" height="40"
    fill="steelBlue" />
  <rect x="70"  y="80" width="40" height="40"
    style="fill: steelBlue" />
  <rect x="130" y="80" width="40" height="40"
    class="fancy" />
</svg>
    
.red {
  fill: red; /* not background-color! */
}

.fancy {
  fill: none;
  stroke: black; /* similar to border-color */
  stroke-width: 3pt; /* similar to border-width */
  stroke-dasharray: 3,5,10;
}

Where HTML has the <div> and <span> tags, SVG has the <g> tag for an arbitrary group. You’ll see <g> a lot in D3 examples. They’re great for applying styles to a group (including re-positioning the groups).

The <text> tag is good for simple labels. The <path> tag is powerful but complex, it can be used for either lines or arbitrary filled-in shapes depending on the styling.

<svg width="300" height="180">
  <g transform="translate(5, 15)">
    <text x="0" y="0">Howdy!</text>
  </g>

  <g transform="translate(5, 55)">
    <!-- M: move to (jump)
         L: line to
         Q: curve to (quadratic) -->
    <path d="M0,50 L50,0 Q100,0 100,50"
      fill="none" stroke-width="3" stroke="black" />
  </g>

  <g transform="translate(5, 105)">
    <!-- C: curve to (cubic)
         Z: close shape -->
    <path d="M0,100 C0,0 25,0 125,100 Z" fill="black" />
  </g>
</svg>
Howdy!

Next