Incorrect element transitions during data reordering in d3.selection.join

Answer

To make d3.selection.join() keep the same DOM nodes bound to the same data items when the array is reordered or filtered, supply a key function as the second argument to .data(). The key function must return a value that is unique and stable for each datum (e.g., an id field).

Confirmed facts

• When .data(data) is called without a key, D3 uses the array index as the implicit key. __data__ on each DOM node is set to the datum that currently occupies that index.
• When a key function key(d) is provided, D3 builds a map from key values to existing nodes. It then matches incoming data to nodes by comparing key(d) values. The __data__ property of a node is updated only when the datum with the matching key is assigned to that node; otherwise the node enters the exit selection.
• This matching step happens before .join() creates the enter, update, and exit selections, so the join works on correctly paired nodes.

Steps for this case

1. Define a stable identifier in your data, e.g., const data = [{id: 'a', value: 1}, {id: 'b', value: 2}, ...];
2. Bind data with the key function before joining:

   const svg = d3.select('svg');
   const circles = svg.selectAll('circle')
       .data(data, d => d.id)   // ← key function
       .join(
         enter => enter.append('circle').attr('r', 5),
         update => update,          // update selection (no change needed)
         exit => exit.remove()
       );
     

3. If you need a transition, apply it only to the update selection (or to the join result via a call):

   circles.call(g => g.transition().duration(500)
         .attr('cx', d => d.value * 10)
         .attr('cy', 50));
     

Likely explanation (if you still see odd transitions)

The most common remaining cause is that the transition is being started on the enter selection instead of update. Verify by logging which nodes receive the start event; only nodes that already existed should animate.