Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 44 ยท Selections and Data Joins

The selection.join Method

Use selection.join in D3 v7 to create, update and remove elements in one call, with function arguments for custom enter.

The enter, update and exit pattern is powerful but verbose. Since D3 version 6, selection.join() does the whole dance in one call. It appends elements for new data, keeps and updates matched ones, removes the leftovers, and returns the merged enter-plus-update selection so you can set shared attributes right away. For most charts you will never need the long form again.

The simplest form

Pass the element name as a string:

JavaScript
svg.selectAll("circle")
  .data(data)
  .join("circle")
  .attr("cx", d => x(d.value))
  .attr("cy", 20)
  .attr("r", 5);

join("circle") does enter().append("circle"), merges enter and update, and calls exit().remove(). The returned selection includes both new and existing elements, so the attributes after it apply to all of them. This replaces about six lines of the classic pattern.

join keeps the DOM in step with the data

The three console lines come from calling render() directly: first with 3 items, then 4, then back to 3. Click the buttons to see the circles follow the data. There is no explicit remove or merge.

Custom enter, update and exit

Sometimes the groups need different treatment. join accepts three functions: one each for enter, update and exit. Each receives the corresponding selection. The enter function must return the entered selection (usually the appended elements) and the update function the updated one. The exit function usually removes.

JavaScript
.join(
  enter => enter.append("circle")
                .attr("r", 0)                  // start state
                .call(e => e.transition().attr("r", d => d.v)),
  update => update
                .call(u => u.transition().attr("r", d => d.v)),
  exit => exit
                .call(x => x.transition().attr("r", 0).remove())
)

The selection join finally returns is the merge of what the enter and update functions returned. That is why you should return the selection in each function (it is easy to forget when you use braces {} rather than an expression body).

Custom enter, update and exit

Going from set 1 to set 2: b and c are updated (orange), d and e enter (green), a exits. The events list proves each function ran once with the expected group.

Join with child elements

join also lets you create a group plus its children in the enter step, a very common pattern for labelled marks such as a bar with a label. The enter function appends a g, adds children to it, and returns the g. The update step can then select the children using .select, which also carries the datum down.

JavaScript
svg.selectAll("g.bar")
  .data(data, d => d.name)
  .join(enter => {
    const g = enter.append("g").attr("class", "bar");
    g.append("rect");
    g.append("text");
    return g;
  })
  .attr("transform", (d, i) => `translate(0, ${i * 28})`)
  .call(g => g.select("rect").attr("width", d => d.v * 3).attr("height", 22))
  .call(g => g.select("text").attr("x", 6).attr("y", 16).text(d => d.name));

Because the joined selection includes both new and old groups, the call blocks update the rectangle and text of every group.

A group with a rect and a label

join versus the classic pattern

Task join
Simple one-to-one mapping .join("tag")
Different initial state for new elements .join(enter => enter.append(...)...)
Animate exit .join(..., ..., exit => exit.transition()...remove())
Need something very custom Classic enter(), exit(), merge() still works

Use join by default. Reach for the explicit form only if you must interleave steps that join cannot express, such as ordering work between enter and update in a way the three callbacks cannot handle.

join also calls selection.order() for you, so the DOM order matches the data order after each update. That makes it safe to use with sorted data.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does selection.join('circle') do?

    join packages the enter, update and exit logic into one call and returns the merge of enter and update.
  2. 2. Which functions does join accept for custom behavior?

    join(enter, update, exit) takes three callbacks, each receiving the respective selection.
  3. 3. What should the enter callback return?

    join merges the returned selections. If you forget to return, newly created elements are missing from the result.
  4. 4. How would you animate elements leaving?

    exit => exit.transition()...remove() keeps the element until the transition ends, then removes it.

Summary

  • selection.join("tag") replaces enter().append(), merge and exit().remove() in one call.
  • Pass three functions (enter, update, exit) for custom behavior; return the selection from enter and update.
  • Create groups with children in the enter function, then use .call and .select to update the children.
  • Always use a key function when elements need stable identity.

Next: Nested Selections and Grouped Data