D3.js .join() DOM ordering with key functions

Direct answer

No. In D3 v6 and v7, .join() does not reorder existing DOM elements when the input data array changes order, even when a key function is supplied. The resulting DOM order is not guaranteed to match the data array.

Confirmed behavior

• Matched elements keep their original DOM position.
• Entering elements are appended to the end of the parent container.
• Exiting elements are removed from their current position.

Likely explanation

.join() is a convenience wrapper around the standard enter-update-exit pattern. It uses the key function to bind data by identity, but the underlying selection operations do not move existing nodes. Reordering the DOM is a separate concern that D3 delegates to the caller.

When this breaks visualizations

SVG z-index layering and CSS transition sequences depend on document order. If you re-sort or shuffle the data array between updates without reordering the DOM, the visual stacking and animation timing will reflect insertion history rather than the current data sequence.

Correcting the order

Call .sort() on the selection after .join() to reposition DOM nodes so they match the data array. Use .order() only if the selection is already sorted and you need to sync the DOM to it.

const rects = svg.selectAll("rect")
  .data(data, d => d.id);

rects.join(
  enter => enter.append("rect"),
  update => update
)
.sort((a, b) => data.indexOf(a) - data.indexOf(b));

Verification

To confirm this in your own code:

1. Bind three elements with unique keys.
2. Swap the key order in the data array and call .join().
3. Inspect the DOM: the elements remain in their original positions.
4. Apply .sort() and verify the DOM nodes shift to match the new array sequence.

If you skip .sort(), treat DOM order as a record of insertion history, not a reflection of the current data order.