30:T939,mdh`D3 6.0 is out! It comes with [exciting new features and improvements](https://observablehq.com/d/08a5160d4c49d1f6). It also introduces a few important API changes. But, do not fear: almost all the methods are behaving exactly as they did with v5; just a handful of them are not backwards compatible. Here's a **comprehensive** list of the changes you will need to watch for when you upgrade to D3 v6: **Adoption of ES2015** * *All* the D3 modules have now adopted ES2015. Developers who need to maintain compatibility with older browsers will use transpilation. [[details](#es2015)] **d3-selection** has a new event manager: * d3.event ⇨ (event) passed as the first argument to all listeners [[details](#events)] * d3.mouse, d3.touch, d3.touches, d3.clientPoint ⇨ d3.pointer [[details](#pointer)] **d3-brush**, **d3-drag** and **d3-zoom** also use the new event manager: * *brush*.on listeners now receive event [[details](#event_brush)] * *drag*.on listeners now receive event [[details](#event_drag)] * *zoom*.on listeners now receive event [[details](#event_zoom)] **d3-voronoi** is deprecated, and replaced by [d3-delaunay](https://d3js.org/d3-delaunay): * d3.voronoi ⇨ d3.Delaunay [[details](#delaunay)] **d3-collection** is deprecated, and its methods are replaced: * d3.nest ⇨ d3.group and d3.rollup (from d3-array) [[details](#group)] * d3.map ⇨ Map [[details](#collection)] * d3.set ⇨ Set [[details](#collection)] * d3.keys ⇨ Object.keys [[details](#collection)] * d3.values ⇨ Object.values [[details](#collection)] * d3.entries ⇨ Object.entries [[details](#collection)] **d3-array** has renamed two methods: * d3.histogram ⇨ d3.bin [[details](#bin)] * d3.scan ⇨ d3.leastIndex [[details](#leastIndex)] **d3-interpolate** has a breaking change in an ancillary method: * d3.interpolateTransformCss is now stricter in its inputs. [[details](#interpolateTransformCss)] **d3-format** changes its minus sign: * The default symbol for the sign of negative values becomes unicode minus instead of hyphen-minus. [[details](#minus)] **bower** * support for the [bower](https://github.com/mbostock-bower/d3-bower) package manager has been dropped; use [unpkg](https://unpkg.com/d3) or [cdnjs](https://cdnjs.com/libraries/d3). _And that is all._ The sections below detail how to upgrade existing code for d3@6. --- `31:T56c,events = mdh`## Event management The global **d3.event** has been removed. It is replaced by a local event passed as the first argument to all listeners: For example, ~~~{js} selection.on("mousemove", function(d) { … do something with ~~~d3.event~~~ and d… }) ~~~ becomes: ~~~{js} selection.on("mousemove", function(___event___, d) { … do something with ___event___ and d … }) ~~~ To be complete, the listeners that used to receive the datum (*d*), index (*i*) and elements (*e*) in the selection now receive the event and datum, with *this* being the target node. As a consequence: ~~~{js} selection.on("click", function(d~~~, i, e~~~) { console.log(d, i, e); }) ~~~ should be replaced by: ~~~{js} selection.on("click", function(___event___, d) { const e = ___selection.nodes()___; const i = ___e.indexOf(this)___; console.log(d, i, e); }) ~~~ Note that [event.currentTarget](https://developer.mozilla.org/en-US/docs/Web/API/Event/currentTarget) gives access to the element to which the listener is bound and can replace *this* in arrow functions: ~~~{js} selection.on("click", (___event___, d) => { console.log(event.currentTarget); }) ~~~ (An alternative technique, when you need the index *i*, is to embed it into the datum, as we do in the [Zoom with tooltip](https://observablehq.com/@d3/zoom-with-tooltip) notebook.) `32:T47c,event_brush = mdh`In **d3.brush**, where a [typical brush handler](https://observablehq.com/@d3/double-click-brush-clear) used to be: ~~~ function brushed() { const selection = ~~~d3.event~~~.selection; if (selection === null) { circle.attr("stroke", null); } else { const [x0, x1] = selection.map(x.invert); circle.attr("stroke", (d) => x0 <= d && d <= x1 ? "red" : null); } } ~~~ you would now use: ~~~ function brushed(___event___) { const selection = ___event___.selection; if (selection === null) { circle.attr("stroke", null); } else { const [x0, x1] = selection.map(x.invert); circle.attr("stroke", (d) => x0 <= d && d <= x1 ? "red" : null); } } ~~~ or even better, by [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) event: ~~~ function brushed(___{selection}___) { if (selection === null) { circle.attr("stroke", null); } else { const [x0, x1] = selection.map(x.invert); circle.attr("stroke", (d) => x0 <= d && d <= x1 ? "red" : null); } } ~~~ `33:T72e,group = mdh`## d3.nest becomes d3.group d3.nest, part of [d3-collection](https://github.com/d3/d3-collection), is gone. Code that used to be: ~~~js node = svg.selectAll("g") .data(~~~d3.nest()~~~.key((d) => d.height).entries(~~~root.descendants()~~~)) ~~~ can be replaced by: ~~~js node = svg.selectAll("g") .data(___d3.group___(___root___, (d) => d.height)) ~~~ The *values* are not in each group’s .values property. Instead, each group presents itself as a [name, values] pair, and values are accessed as d[1]: ~~~js selection .data((d) => ~~~d.values~~~) .data((d) => ___d[1]___) ~~~ Or with destructuring: ~~~js selection .data(~~~(d) => d.values~~~) .data(___([, values]) => values___) ~~~ To replace the *nest*.sortKeys and *nest*.sortValues methods, you might have to use d3.groups, which returns the map as an array of [key, value] pairs. This array can then be sorted like so: ~~~js d3.groups(data, (d) => d.key) .___sort((a, b) => d3.ascending(a[0], b[0])___; // sort by ascending key d3.groups(data, (d) => d.key) .___sort((a, b) => d3.ascending(d3.sum(a[1]), d3.sum(b[1]))___; // sort by ascending sum of values ~~~ An alternative, more powerful approach is to [apply d3.hierarchy](https://observablehq.com/d/9a453665f405eebf) to the result returned by d3.group. This offers sorting as well as all sorts of tree-traversal techniques. The rollup method of d3.nest is replaced by d3.rollup (and d3.rollups in array form): ~~~js ~~~d3.nest()~~~.key((d) => d.key).rollup((v) => v.length).entries(data); ~~~ becomes: ~~~js ___d3.rollup___(data, (v) => v.length, (d) => d.key); ~~~ For an interesting example, see https://observablehq.com/@d3/cascaded-treemap Note that, if you have a complex application using d3.nest, you can still load d3-collection as an independent module. `34:T416,delaunay = mdh`## Voronoi becomes Delaunay The [d3-voronoi](https://github.com/d3/d3-voronoi) module is now obsolete, and d3@6 bundles the [d3-delaunay](https://d3js.org/d3-delaunay) module instead, which is both faster and more robust. The changes, however, cannot be summarized easily: the algorithms, data structure and API have changed. But the documentation for the new d3.Delaunay is exhaustive, with [many examples](https://observablehq.com/collection/@d3/d3-delaunay), such as this “[Voronoi labels](https://observablehq.com/@d3/voronoi-labels)” notebook. For a simple use-case, this code: ~~~js const cells = ~~~d3.voronoi~~~() .extent([[-1, -1], [width + 1, height + 1]]) .polygons(~~~data~~~) ~~~ becomes: ~~~js const delaunay = ___d3.Delaunay.from(data)___ const voronoi = delaunay.voronoi([-1, -1, width + 1, height + 1]) const cells = voronoi.cellPolygons(); // an iterator ~~~ Note that, if you have a complex application using the older d3-voronoi API, you can still load d3-voronoi as an independent module. `35:[] 2e:{"title":"D3 6.0 migration guide","cells":[{"id":0,"value":"# D3 6.0 migration guide","pinned":false,"hidden":false,"mode":"md"},{"id":2,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":85,"value":"es2015 = mdh`## Moving to ES2015\n\nD3 has adopted **ECMAScript 2015**, also called **ES6**, across the board. Its code base is gradually moving to using the new features (iterators, arrow functions, etc.).\n\nTo mark this change, all the modules in D3 have received a major version update, and we deliberately introduced some ES6 syntax in all of them so that build tools expecting ES5 will immediately alert.\n\nThis means that D3@6 does not maintain compatibility with older browsers. Developers can use transpilation tools such as [babel](https://babeljs.io/setup) to do so.`\n\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":211,"value":"collection = mdh`**d3-collection** is removed in favor of native ES2015 features.\n\nSo for example instead of:\n~~~js\n var map = ~~~d3.map~~~()\n .set(\"foo\", 1)\n .set(\"bar\", 2);\n map.get(\"foo\"); // 1\n~~~\n\none should now use\n~~~js\n const map = ___new Map___()\n .set(\"foo\", 1)\n .set(\"bar\", 2);\n map.get(\"foo\"); // 1\n~~~\n\nor\n~~~js\n const map = ___new Map___([[\"foo\", 1], [\"bar\", 2]]);\n map.get(\"foo\"); // 1\n~~~\n\nThe native Map object is iterable, and works as well with D3’s selections and other methods:\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":251,"value":"map = new Map([[\"foo\", 1], [\"bar\", 2]]) // creates a Map","pinned":true,"hidden":false,"mode":"ojs"},{"id":238,"value":"// creates elements from a Map\ncircles = d3\n .create(\"svg\")\n .selectAll(\"circle\")\n .data(map)\n .join(\"circle\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":260,"value":"circles.size()","pinned":true,"hidden":false,"mode":"ojs"},{"id":249,"value":"// creates a Map from a selection’s data\nnew Map(circles.data())","pinned":true,"hidden":false,"mode":"ojs"},{"id":262,"value":"mdh`Similarly, d3.set can be replaced with Set, d3.keys by Object.keys, d3.values by Object.values and d3.entries by Object.entries.\n\nThe critical differences between these methods and native JS are highlighted in the documentation for the deprecated [d3-collection](https://github.com/d3/d3-collection/blob/master/README.md#maps).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":6,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":427,"value":"## Brush, drag, zoom events\n\nThe new event system applies to listeners across the board, not only in d3-selection, but also in d3-drag, d3-brush and d3-zoom:","pinned":false,"hidden":false,"mode":"md"},{"id":298,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":413,"value":"event_drag = mdh`In **d3.drag**, where a [typical drag handler](https://observablehq.com/@d3/drag-svg-voronoi-clipped) used to be:\n~~~js\n d3.drag()\n .on(\"start\", ~~~(d)~~~ => circle.filter(p => p === d).raise().attr(\"stroke\", \"black\"))\n .on(\"drag\", ~~~(d)~~~ => (d.x = ~~~d3.event~~~.x, d.y = ~~~d3.event~~~.y))\n .on(\"end\", ~~~(d)~~~ => circle.filter(p => p === d).attr(\"stroke\", null))\n~~~\n\nyou would now use:\n~~~js\n d3.drag()\n .on(\"start\", ___(event, d)___ => circle.filter(p => p === d).raise().attr(\"stroke\", \"black\"))\n .on(\"drag\", ___(event, d)___ => (d.x = ___event___.x, d.y = ___event___.y))\n .on(\"end\", ___(event, d)___ => circle.filter(p => p === d).attr(\"stroke\", null))\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":420,"value":"event_zoom = mdh`In **d3.zoom**, where a [typical zoom handler](https://observablehq.com/@d3/drag-zoom) used to be:\n~~~js\n function zoomed(d) {\n g.attr(\"transform\", ~~~d3.event~~~.transform);\n }\n~~~\n\nyou would now use:\n~~~js\n function zoomed(___event___, d) {\n g.attr(\"transform\", ___event___.transform);\n }\n~~~\n\nor, destructuring \\`event\\`:\n~~~js\n function zoomed(___{transform}___, d) {\n g.attr(\"transform\", transform);\n }\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":9,"value":"pointer = mdh`## Mouse, touch, touches\n\nAs a consequence the way we read the mouse or touch event positions has changed too: the functions **d3.mouse**, **d3.touch**, **d3.touches** and **d3.clientPoint** have been removed, and replaced by [d3.pointer](https://d3js.org/d3-selection/events#pointer) and, if you want to support multitouch, [d3.pointers](https://d3js.org/d3-selection/events#pointers).\n\nFor example,\n\n~~~{js}\n selection.on(\"mousemove\", function() {\n … ~~~d3.mouse~~~(this) …\n })\n~~~\n\nbecomes:\n~~~{js}\n selection.on(\"mousemove\", (___event___) => {\n … ___d3.pointer___(___event___) …\n })\n~~~\n\n\n(d3.pointer is an enhanced version of the removed d3.clientPoint method.)\n\nFor a more detailed example see [Multitouch done right](https://observablehq.com/@d3/multitouch).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":27,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":368,"value":"bin = mdh`## d3.bin replaces d3.histogram\n\nThis is a simple name change with the exact same API.\n\n~~~js\n ~~~d3.histogram~~~(…)\n~~~\n\nbecomes\n~~~js\n ___d3.bin___(…)\n~~~\n\n(d3.histogram is still present as a deprecated alias.)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":367,"value":"leastIndex = mdh`## d3.leastIndex replaces d3.scan\n\n[d3.leastIndex](link to readme) has the same signature as d3.scan:\n\n~~~js\n d3.~~~scan~~~([2, 0, 3]); // 1\n~~~\nbecomes:\n~~~js\n d3.___leastIndex___([2, 0, 3]); // 1\n~~~\n\nHowever d3.leastIndex returns \\`—1\\` instead of \\`undefined\\` when the data contains no comparable element:\n\n~~~js\n const i = d3.~~~scan~~~([{a:1}, {a:2}, {a:0}], (d) => d.b);\n if ~~~(i === undefined)~~~ { return \"not found!\"; }\n~~~\n\nbecomes:\n\n~~~js\n const i = d3.___leastIndex___([{a:1}, {a:2}, {a:0}], (d) => d.b);\n if ___(i < 0)___ { return \"not found!\"; }\n~~~\n\nThis situation can arise when the data array is empty:\n~~~js\n d3.scan([]); // undefined\n d3.leastIndex([]); // -1\n~~~\n\n(d3.scan is still present as a deprecated method.)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":18,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":514,"value":"interpolateTransformCss = mdh`## d3.interpolateTransformCss is stricter\n\n[d3.interpolateTransformCss](https://d3js.org/d3-interpolate/transform#interpolateTransformCss) now uses DOMMatrix to operate on transforms which are not necessary bounded to a node. As a consequence, interpolating between transforms that have been defined with relative lengths (such as *em*) is not permitted anymore and throws an error.\n\n~~~js\n const interpolator = d3.interpolateTransformCss(\n \"translateY(~~~80%~~~) scale(2)\",\n \"translateX(~~~3em~~~) rotate(5deg)\"\n );\n~~~\n\nmust now be converted to absolute lengths:\n\n~~~js\n const interpolator = d3.interpolateTransformCss(\n \"translateY(___800px___) scale(2)\",\n \"translateX(___30px___) rotate(5deg)\"\n );\n~~~\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":549,"value":"minus = mdh`## d3-format now uses unicode minus\n\nThe minus sign is formatted with the unicode character “minus” (U+2212) instead of “hyphen-minus” (U+002D), resulting in more typographically correct rendering (“−10” vs “-10”). Use [d3.formatLocale](https://d3js.org/d3-format#formatLocale) or [d3.formatDefaultLocale](https://d3js.org/d3-format#formatDefaultLocale) if you need this to be a hyphen-minus:\n\n~~~js\n d3.formatDefaultLocale({\n thousands: \",\",\n grouping: [3],\n ___minus: \"-\",___\n currency: [\"$\", \"\"]\n })\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":564,"value":"---\n## Annex\n\nThanks to [Guillaume Levrier](/@guillaume-levrier) for suggestions.","pinned":false,"hidden":false,"mode":"md"},{"id":567,"value":"// markdown with yellow and pink highlights\nmdh = {\n const hljs = window.hljs || (await require(\"@observablehq/highlight.js\"));\n\n return function() {\n const node = md(...arguments);\n for (const fragment of node.querySelectorAll(\"code\")) {\n hljs.highlightBlock(fragment);\n\n fragment.innerHTML = fragment.innerHTML.replace(\n /___(.*?)___/g,\n '$1'\n );\n fragment.innerHTML = fragment.innerHTML.replace(\n /~~~(.*?)~~~/g,\n '$1'\n );\n }\n\n return node;\n };\n}","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}