Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 44 ยท Selections and Data Joins

Binding Data to Elements in D3

Understand how selection.data() and datum() attach data to DOM elements, how the __data__ property works, what happens with more or fewer items.

Binding data is the "D" in D3. When you call selection.data(array), D3 pairs each element in the selection with one item of the array and stores that item on the element itself, in a property called __data__. From then on, every accessor function (d, i) => ... receives that item as d. This lesson explains what the pairing does, what happens when counts differ, and how keys keep the pairing stable.

data() pairs by index

By default, data() pairs the first element with the first datum, the second with the second, and so on. This is "join by index".

JavaScript
d3.selectAll("li").data(["a", "b", "c"]);

If there are three li elements, the first gets "a", the second "b", the third "c". You can read it back with selection.data() (no arguments returns the array of data) or from the node: node.__data__.

Data lives on the element

The data array can hold anything: numbers, strings, arrays, objects. Objects are the usual choice because a chart needs several fields per mark (a name, a value, a category).

The three groups: enter, update, exit

When the number of elements and data items differ, data() returns a selection of the update group (elements that matched a datum) and exposes two more groups:

  • selection.enter(): data that has no element yet. You append elements for them.
  • selection.exit(): elements that have no datum anymore. You usually remove them.
flowchart LR
  D["Data: 5 items"] --> J{"data() pairs by index or key"}
  E["Elements: 3 existing"] --> J
  J --> U["update: 3 matched"]
  J --> N["enter: 2 new data"]
  J --> X["exit: 0 leftover elements"]

With five data items and three elements, two items fall in enter and none in exit.

The full workflow is in Enter, Update and Exit, and the shortcut join() in The join Method. Here you only need the idea: data() computes the three groups, and you decide what to do with each.

Counting the groups

Key functions: pairing by identity

Pairing by index is wrong when data reorders or items are inserted: element 0 would suddenly show a different item. Give data() a second argument, a key function, to pair by identity instead. It runs for each datum (with d) and for each existing element (using the datum already bound, with this as the node), and items with equal keys are matched.

JavaScript
selection.data(newData, d => d.id);

The key is converted to a string, so "7" and 7 are the same key. If two data items return the same key, the second is placed in enter and D3 ignores it for matching, so keys must be unique.

Index versus key pairing

The key-based result is what you want in animated charts: the element that represented "a" stays the element for "a", so it can animate smoothly to its new place instead of morphing into "c".

datum(): bind one value without the join

selection.datum(value) binds the same value to every element without computing enter/exit groups. Use it when each selected element is already one chart and the data belongs to it, for example a single path that receives a whole array.

JavaScript
d3.select("path.line")
  .datum(series)            // the whole array is the datum
  .attr("d", lineGenerator); // lineGenerator(series) gives the path string

The rule of thumb: data() for many elements, one per item; datum() for one element that needs the entire dataset (line, area, a single pie arc generator call). data also differs in returning the update selection; datum returns the same selection.

Data is inherited by children

append (and select) copy the parent's datum to the new child. So after g.data(rows).join("g"), calling .append("text").text(d => d.name) works inside each group without re-binding. selectAll, however, does not inherit data, because it creates new groups. Remember this when you see missing data in nested elements: it usually comes from using selectAll where select was needed. Nested Selections goes deeper.

Setting .data() is not a drawing operation. Nothing changes on screen until you set attributes, styles or text using the data. A common beginner pattern is to call data() and wonder why the page is unchanged.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does D3 store the datum bound to an element?

    D3 attaches the datum to the node as node.data, which is why accessor functions can read it later.
  2. 2. You have 3 elements and call data() with 5 items. What are the group sizes?

    Three elements match the first three data items. The remaining two items have no element, so they are in enter.
  3. 3. When should you pass a key function to data()?

    Without keys, items are paired by index, so reordering reassigns data. Keys keep identity stable.
  4. 4. Which is appropriate for a single <path> that draws an entire time series?

    datum binds the whole array to the one element without computing enter and exit groups.

Summary

  • data(array) stores items on elements (__data__); accessors then receive them as d.
  • Pairing is by index unless you pass a key function; keys must be unique.
  • data() computes update, enter and exit groups; datum() just binds a value.
  • append and select pass the parent's datum to children; selectAll does not.

Next: Enter, Update and Exit