• Adopt exact paths for imports.
• Adopt explicit files for publishing.
• Add sideEffects: false to the package.json.
• Update dependencies.

• Add selection.join!
• Fix selection.order to enforce relative position, rather than exact siblings.
• Remove vendor fallback for element.matches.

• Housekeeping.

• Update dependencies.

• Add selection.clone. (#149)
• Add d3.create. (#156)

• Add d3.clientPoint.

• Add d3.style.
• Change selection.style to return the inline style, if present. (#120)

• Fix usage of CustomEvent in IE11. Thanks, @nathanbowser! (#126)

• Add module entry point to package.json.

• First stable release.
• d3.select and d3.selectAll now return an empty selection if the selector is null (#79).
• selection.select, selection.selectAll now return an empty selection if the selector is null (#79).

Changes since D3 3.x

Selections no longer subclass Array using prototype chain injection; they are now plain objects, improving performance. The internal fields (selection._groups, selection._parents) are private; please use the documented public API to manipulate selections. The new selection.nodes method generates an array of all nodes in a selection.

Selections are now immutable: the elements and parents in a selection never change. (The elements’ attributes and content will of course still be modified!) The selection.sort and selection.data methods now return new selections rather than modifying the selection in-place. In addition, selection.append no longer merges entering nodes into the update selection; use selection.merge to combine enter and update after a data join. For example, the following general update pattern in 3.x:

var circle = svg.selectAll("circle").data(data) // UPDATE
    .style("fill", "blue");

circle.exit().remove(); // EXIT

circle.enter().append("circle") // ENTER; modifies UPDATE! 🌶
    .style("fill", "green");

circle // ENTER + UPDATE
    .style("stroke", "black");

Would be rewritten in 4.0 as:

var circle = svg.selectAll("circle").data(data) // UPDATE
    .style("fill", "blue");

circle.exit().remove(); // EXIT

circle = circle.enter().append("circle") // ENTER
    .style("fill", "green")
  .merge(circle) // ENTER + UPDATE
    .style("stroke", "black");

This change is discussed further in What Makes Software Good.

In 3.x, the selection.enter and selection.exit methods were undefined until you called selection.data, resulting in a TypeError if you attempted to access them. In 4.0, now they simply return the empty selection if the selection has not been joined to data.

In 3.x, selection.append would always append the new element as the last child of its parent. A little-known trick was to use selection.insert without specifying a before selector when entering nodes, causing the entering nodes to be inserted before the following element in the update selection. In 4.0, this is now the default behavior of selection.append; if you do not specify a before selector to selection.insert, the inserted element is appended as the last child. This change makes the general update pattern preserve the relative order of elements and data. For example, given the following DOM:

<div>a</div>
<div>b</div>
<div>f</div>

And the following code:

var div = d3.select("body").selectAll("div")
  .data(["a", "b", "c", "d", "e", "f"], function(d) { return d || this.textContent; });

div.enter().append("div")
    .text(function(d) { return d; });

The resulting DOM will be:

<div>a</div>
<div>b</div>
<div>c</div>
<div>d</div>
<div>e</div>
<div>f</div>

Thus, the entering c, d and e are inserted before f, since f is the following element in the update selection. Although this behavior is sufficient to preserve order if the new data’s order is stable, if the data changes order, you must still use selection.order to reorder elements.

There is now only one class of selection. 3.x implemented enter selections using a special class with different behavior for enter.append and enter.select; a consequence of this design was that enter selections in 3.x lacked certain methods. In 4.0, enter selections are simply normal selections; they have the same methods and the same behavior. Enter nodes now implement node.appendChild, node.insertBefore, node.querySelector, and node.querySelectorAll.

The selection.data method has been changed slightly with respect to duplicate keys. In 3.x, if multiple data had the same key, the duplicate data would be ignored and not included in enter, update or exit; in 4.0 the duplicate data is always put in the enter selection. In both 3.x and 4.0, if multiple elements have the same key, the duplicate elements are put in the exit selection. Thus, 4.0’s behavior is now symmetric for enter and exit, and the general update pattern will now produce a DOM that matches the data even if there are duplicate keys.

Selections have several new methods! Use selection.raise to move the selected elements to the front of their siblings, so that they are drawn on top; use selection.lower to move them to the back. Use selection.dispatch to dispatch a custom event to event listeners.

When called in getter mode, selection.data now returns the data for all elements in the selection, rather than just the data for the first group of elements. The selection.call method no longer sets the this context when invoking the specified function; the selection is passed as the first argument to the function, so use that. The selection.on method now accepts multiple whitespace-separated typenames, so you can add or remove multiple listeners simultaneously. For example:

selection.on("mousedown touchstart", function() {
  console.log(d3.event.type);
});

The arguments passed to callback functions has changed slightly in 4.0 to be more consistent. The standard arguments are the element’s datum (d), the element’s index (i), and the element’s group (nodes), with this as the element. The slight exception to this convention is selection.data, which is evaluated for each group rather than each element; it is passed the group’s parent datum (d), the group index (i), and the selection’s parents (parents), with this as the group’s parent.

The new d3.local provides a mechanism for defining local variables: state that is bound to DOM elements, and available to any descendant element. This can be a convenient alternative to using selection.each or storing local state in data.

The d3.ns.prefix namespace prefix map has been renamed to d3.namespaces, and the d3.ns.qualify method has been renamed to d3.namespace. Several new low-level methods are now available, as well. d3.matcher is used internally by selection.filter; d3.selector is used by selection.select; d3.selectorAll is used by selection.selectAll; d3.creator is used by selection.append and selection.insert. The new d3.window returns the owner window for a given element, window or document. The new d3.customEvent temporarily sets d3.event while invoking a function, allowing you to implement controls which dispatch custom events; this is used by d3-drag, d3-zoom and d3-brush.

For the sake of parsimony, the multi-value methods—where you pass an object to set multiple attributes, styles or properties simultaneously—have been extracted to d3-selection-multi and are no longer part of the default bundle. The multi-value map methods have also been renamed to plural form to reduce overload: selection.attrs, selection.styles and selection.properties.

See CHANGES for all D3 changes since 3.x.

• Changed selection.filter to no longer preserve index; use selection.select instead.

• Export to the global d3 in vanilla environments (d3/d3#2840).
• Add selection.insert (#65).
• Change selection.append to no longer take an optional before selector (#65).
• Add d3.local (#74).

• Fix treatment of duplicate keys in selection.data (d3/d3-axis#10).

• Add d3.customEvent.
• Optimize selection.raise and selection.lower.

• Remove workaround for ancient WebKit bug.

• Selections are now immutable!
• Changed selection.sort to return a new selection.
• Changed selection.data to return a new selection.
• Changed selection.enter to be non-destructive.
• Changed selection.exit to be non-destructive.
• Changed selection.filter to preserve index.
• Removed magic copy-to-update behavior of enter.append.
• Added selection.merge.

• Fix selection.constructor (#61).

• Fix implicit namespace in non-HTML documents (mbostock/d3#2737).

• Use copy-on-write when modifying selections (#58).

• You can now specify multiple typenames to selection.on (#59).
• Fix polyfill for mouseenter and mouseleave in selection.on.

• Expose d3.window.

• Expose d3.creator.
• Expose d3.matcher.
• Expose d3.selector.
• Expose d3.selectorAll.

• Rename private selection._nodes field to selection._groups.

• Fix case-sensitivity of selection.append in case-insensitive documents (mbostock/d3#2722).

• Fix d3.select and d3.selectAll to set the parent to the document element when passed a selector.
• Fix selection.data to pass the values function the parents array.
• Fix selection.append to append entering nodes as the last child when the before selector is null.
• Add tests.

• Fix selection.classed.
• Fix selection.sort.
• Fix selection.text.
• Fix d3.point on WebKit browsers.

• Add selection.raise and selection.lower.
• Selections are now bilevel, as in D3 3.x, not arbitrary hierarchies.
• Selections functions now take the current datum d, index i and group nodes as arguments.
• Change selection.enter and selection.exit to reset enter and exit after access.
• Change selection.call to no longer set the this context.
• Fix d3.namespace to string-coerce.
• Fix selection.classed when element.getAttribute returns null.
• Fix enter.select to not clear the enter selection.
• Fix enter nodes for element.querySelectorAll.
• The requote function is no longer exported.
• Selection methods have been optimized.

• Fix selection.append with a before selector on enter selections.

• Fix selection.data on flat selections (#44).
• Remove selection.event; use selection.on instead.
• Remove selection.class; use selection.classed instead.
• Remove selection.insert; use selection.append instead.
• Improve the README.

• Define d3-selection module (and d3_selection global), not selection.

• Fix name of exported event binding (see rollup/rollup#268).

• Adjust package.json definition for npm users.

• Remove Map polyfill; namespaces is now a plain object.