selection.join D3’s data join lets you specify exactly what happens to the DOM as data changes. This makes it fast—you can minimize DOM operations—and expressive—you can animate enter, update and exit separately. Yet power comes at a cost: the data join’s generality makes it hard to learn and easy to forget. What if D3 offered a more convenient and memorable API for joining data without sacrificing this power? Enter d3-selection 1.4’s selection.join. Let’s start with the simple case of creating elements from nothing.
{ const svg = d3.create("svg") .attr("width", width) .attr("height", 33) .attr("viewBox", `0 -20 ${width} 33`); svg.selectAll("text") .data(randomLetters()) .join("text") .attr("x", (d, i) => i * 16) .text(d => d); return svg.node(); }
Above, selection.join appends a new SVG text element for each letter. Not too different from enter-append right? Well, hold on to your butts. 🍑
{ const svg = d3.create("svg") .attr("width", width) .attr("height", 33) .attr("viewBox", `0 -20 ${width} 33`); while (true) { svg.selectAll("text") .data(randomLetters()) .join("text") .attr("x", (d, i) => i * 16) .text(d => d); yield svg.node(); await Promises.tick(2500); } }
If the joining selection isn’t empty—as on subsequent iterations of the loop above— selection.join appends entering elements and removes exiting elements to match the data! Entering and updating elements are merged (and ordered), allowing chained operations on the result. This is more concise than the previous general update pattern, but the best part is that you can still control what happens on enter, update and exit as desired!
{ const svg = d3.create("svg") .attr("width", width) .attr("height", 33) .attr("viewBox", `0 -20 ${width} 33`); while (true) { svg.selectAll("text") .data(randomLetters(), d => d) .join( enter => enter.append("text") .attr("fill", "green") .text(d => d), update => update .attr("fill", "gray") ) .attr("x", (d, i) => i * 16); yield svg.node(); await Promises.tick(2500); } }
Above, instead of passing a string to selection.join, separate functions are passed to handle enter and update. (You can pass a third function for exit, as shown below.) The returned enter and update selections are again merged and returned by selection.join. Note the key function, which specifies how to bind data so that the text content only needs to be set on enter.
By passing functions to selection.join, you can not only mininize DOM operations, but also animate enter, update and exit! ✨
{ const svg = d3.create("svg") .attr("width", width) .attr("height", 33) .attr("viewBox", `0 -20 ${width} 33`); while (true) { const t = svg.transition() .duration(750); svg.selectAll("text") .data(randomLetters(), d => d) .join( enter => enter.append("text") .attr("fill", "green") .attr("x", (d, i) => i * 16) .attr("y", -30) .text(d => d) .call(enter => enter.transition(t) .attr("y", 0)), update => update .attr("fill", "black") .attr("y", 0) .call(update => update.transition(t) .attr("x", (d, i) => i * 16)), exit => exit .attr("fill", "brown") .call(exit => exit.transition(t) .attr("y", 30) .remove()) ); yield svg.node(); await Promises.tick(2500); } }
The return value of the enter and update function is important—it specifies the selections to merge and return by selection.join. To avoid breaking the method chain, use selection.call to create transitions. Or, return an undefined enter or update selection to prevent merging. Thanks for reading and using D3! 🙏
Appendix
function randomLetters() { return d3.shuffle("abcdefghijklmnopqrstuvwxyz".split("")) .slice(0, Math.floor(6 + Math.random() * 20)) .sort(); }
d3 = require("d3@^5.8")
html`<style> .observablehq > svg:only-child { font: var(--mono_fonts); display: block; } </style>`