Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 44 ยท Selections and Data Joins

Enter, Update and Exit: The General Update Pattern

Learn the classic D3 data join with enter(), exit(), merge() and remove(): create elements for new data, update existing ones and remove leftovers.

Charts change. A filter hides rows, a new month arrives, a user sorts a list. The data join is how D3 keeps the DOM in step with the data without rebuilding everything. You describe what each item should look like, and D3 tells you which elements need to be created, which updated, and which removed. The three groups are called enter, update and exit.

The three groups in one picture

flowchart TB
  subgraph Data
    D1["new item"]
    D2["existing item"]
  end
  subgraph DOM
    E1["existing element (matched)"]
    E2["element with no data"]
  end
  D1 -->|"no element"| ENTER["enter: append new elements"]
  D2 --- E1
  E1 --> UPDATE["update: change attributes"]
  E2 --> EXIT["exit: remove"]

Enter = data without elements. Update = data and elements paired. Exit = elements without data.

The classic pattern

Written out explicitly, this is the pattern you will see in older D3 code and in many answers online:

JavaScript
const circles = svg.selectAll("circle").data(data, d => d.id);

circles.exit().remove();                       // 1. remove leftovers

const entered = circles.enter().append("circle"); // 2. create for new data
  entered.attr("r", 0);                         //    (initial state)

entered.merge(circles)                          // 3. new + existing together
  .attr("cx", d => d.x)
  .attr("cy", d => d.y)
  .attr("r", 8);

The key trick is merge. enter().append() returns only the new elements, while circles (the update selection) holds only the existing ones. merge combines them so shared attributes are set once. Without it, new elements would be styled but old ones not, or the code would be duplicated.

The explicit pattern: a data refresh

The three console lines show how each dataset sits against the previous one. Going from A (x, y, z) to B (y, z, w, q): y and z are updated, w and q enter, x exits. The buttons let you replay these transitions.

Giving enter its own styles

Often new elements need an initial state that differs from the final one, for example start invisible and fade in. Set the initial state on the entered selection, then apply the common state to the merge. With transitions this gives smooth appearance animations.

JavaScript
const entered = circles.enter().append("circle")
  .attr("cx", d => x(d.id))
  .attr("r", 0)               // grows from nothing
  .attr("fill", "green");

entered.merge(circles)
  .attr("r", d => radius(d.v)); // update and enter both end here

Selecting different update logic

Sometimes the exit and enter branches need different behavior: a leaving element might shrink away before removal, or a new element might be styled differently than the update. The classic pattern makes that explicit because each group is its own selection:

Group Typical code
exit .exit().remove() or .exit().transition().attr("r", 0).remove()
enter .enter().append("tag").attr(initial state)
update the original data() result, modify only the changing attributes
enter.merge(update) attributes shared by both

The most frequent mistake is forgetting exit().remove(). The chart seems fine when data grows, but when it shrinks, stale marks remain on screen. Always handle all three groups, or use selection.join, which does it for you.

Elements you appended earlier are "update" on the next call

Two details trip people up:

  1. Calling selectAll("circle") selects all existing circles in the container, including ones you appended some other way. If your container also holds decoration circles (a legend, say), select within a dedicated group or give data-bound circles a class: selectAll("circle.point"). Use the same selector in every call.
  2. With index pairing (no key function) the exit group is always the tail of the elements, so shrinking data removes the last elements, which can look wrong if the first items disappeared. Use keys to remove the right ones.
Why you should set a class and a key

Because the join works on circle.point only, the legend circle is never touched. If you had used selectAll("circle"), the legend would have been counted, treated as data-less, and removed.

From explicit to join

The explicit pattern is verbose, but it is worth knowing: it shows exactly what happens, and you need it for custom behavior in each group. In D3 v6 and later, selection.join() wraps it. The next lesson covers join with function arguments so you get custom enter, update and exit behavior in one tidy call: The join Method.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is merge needed in the explicit pattern?

    The enter and update selections are separate. merge combines them so common attributes are set once.
  2. 2. Which group should you usually call remove() on?

    exit holds elements whose data is gone, and remove() deletes them from the DOM.
  3. 3. What happens if you shrink the data without a key function and skip exit().remove()?

    D3 never removes elements on its own. The exit group is just a selection that you must act on.
  4. 4. Why use selectAll('circle.point') instead of selectAll('circle') in a container that also has other circles?

    A join manages every element that the selector matches. A specific selector protects unrelated elements.

Summary

  • data() splits the world into enter (new data), update (matched) and exit (leftover elements).
  • The classic pattern is exit().remove(), enter().append() with initial attributes, then merge for shared updates.
  • Key functions keep identity stable; class-specific selectors protect unrelated elements.
  • Forgetting exit().remove() leaves stale marks.

Next: The join Method