d3/docs/d3-selection/modifying.md

Modifying elements

After selecting elements, use the selection to modify the elements. For example, to set the class and color style of all paragraph elements in the current document:

d3.selectAll("p")
    .attr("class", "graf")
    .style("color", "red");

Selection methods typically return the current selection, or a new selection, allowing the concise application of multiple operations on a given selection via method chaining. The above is equivalent to:

const p = d3.selectAll("p");
p.attr("class", "graf");
p.style("color", "red");

Selections are immutable. All selection methods that affect which elements are selected (or their order) return a new selection rather than modifying the current selection. However, note that elements are necessarily mutable, as selections drive transformations of the document!

selection.attr(name, value)

Source · If a value is specified, sets the attribute with the specified name to the specified value on the selected elements and returns this selection.

selection.attr("color", "red")

If the value is a constant, all elements are given the same attribute value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s attribute. A null value will remove the specified attribute.

selection.attr("color") // "red"

If a value is not specified, returns the current value of the specified attribute for the first (non-null) element in the selection. This is generally useful only if you know that the selection contains exactly one element.

The specified name may have a namespace prefix, such as xlink:href to specify the href attribute in the XLink namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map.

selection.classed(names, value)

Source · If a value is specified, assigns or unassigns the specified CSS class names on the selected elements by setting the class attribute or modifying the classList property and returns this selection.

selection.classed("foo", true)

The specified names is a string of space-separated class names. For example, to assign the classes foo and bar to the selected elements:

selection.classed("foo bar", true)

If the value is truthy, then all elements are assigned the specified classes; otherwise, the classes are unassigned.

selection.classed("foo", () => Math.random() > 0.5)

If the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to assign or unassign classes on each element.

selection.classed("foo") // true, perhaps

If a value is not specified, returns true if and only if the first (non-null) selected element has the specified classes. This is generally useful only if you know the selection contains exactly one element.

selection.style(name, value, priority)

Source · If a value is specified, sets the style property with the specified name to the specified value on the selected elements and returns this selection.

selection.style("color", "red")

If the value is a constant, then all elements are given the same style property value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s style property. A null value will remove the style property. An optional priority may also be specified, either as null or the string important (without the exclamation point).

selection.style("color") // "red"

If a value is not specified, returns the current value of the specified style property for the first (non-null) element in the selection. The current value is defined as the element’s inline value, if present, and otherwise its computed value. Accessing the current style value is generally useful only if you know the selection contains exactly one element.

:::warning CAUTION Unlike many SVG attributes, CSS styles typically have associated units. For example, 3px is a valid stroke-width property value, while 3 is not. Some browsers implicitly assign the px (pixel) unit to numeric values, but not all browsers do: IE, for example, throws an “invalid arguments” error! :::

selection.property(name, value)

Source · Some HTML elements have special properties that are not addressable using attributes or styles, such as a form field’s text value and a checkbox’s checked boolean. Use this method to get or set these properties.

selection.property("checked", true)

If a value is specified, sets the property with the specified name to the specified value on selected elements. If the value is a constant, then all elements are given the same property value; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s property. A null value will delete the specified property.

selection.property("checked") // true, perhaps

If a value is not specified, returns the value of the specified property for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

selection.text(value)

Source · If a value is specified, sets the text content to the specified value on all selected elements, replacing any existing child elements.

selection.text("Hello, world!")

If the value is a constant, then all elements are given the same text content; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s text content. A null value will clear the content.

selection.text() // "Hello, world!"

If a value is not specified, returns the text content for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

selection.html(value)

Source · If a value is specified, sets the inner HTML to the specified value on all selected elements, replacing any existing child elements.

selection.html("Hello, <i>world</i>!")

If the value is a constant, then all elements are given the same inner HTML; otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The function’s return value is then used to set each element’s inner HTML. A null value will clear the content.

selection.html() // "Hello, <i>world</i>!"

If a value is not specified, returns the inner HTML for the first (non-null) element in the selection. This is generally useful only if you know the selection contains exactly one element.

Use selection.append or selection.insert instead to create data-driven content; this method is intended for when you want a little bit of HTML, say for rich formatting. Also, selection.html is only supported on HTML elements. SVG elements and other non-HTML elements do not support the innerHTML property, and thus are incompatible with selection.html. Consider using XMLSerializer to convert a DOM subtree to text. See also the innersvg polyfill, which provides a shim to support the innerHTML property on SVG elements.

selection.append(type)

Source · If the specified type is a string, appends a new element of this type (tag name) as the last child of each selected element, or before the next following sibling in the update selection if this is an enter selection. The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data; however, note that selection.order may still be required if updating elements change order (i.e., if the order of new data is inconsistent with old data).

If the specified type is a function, it is evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) For example, to append a paragraph to each DIV element:

d3.selectAll("div").append("p");

This is equivalent to:

d3.selectAll("div").append(() => document.createElement("p"));

Which is equivalent to:

d3.selectAll("div").select(function() {
  return this.appendChild(document.createElement("p"));
});

In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as selection.select.

The specified name may have a namespace prefix, such as svg:text to specify a text attribute in the SVG namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, svg implies svg:svg).

selection.insert(type, before)

Source · If the specified type is a string, inserts a new element of this type (tag name) before the first element matching the specified before selector for each selected element. For example, a before selector :first-child will prepend nodes before the first child. If before is not specified, it defaults to null. (To append elements in an order consistent with bound data, use selection.append.)

Both type and before may instead be specified as functions which are evaluated for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). The type function should return an element to be inserted; the before function should return the child element before which the element should be inserted. For example, to append a paragraph to each DIV element:

d3.selectAll("div").insert("p");

This is equivalent to:

d3.selectAll("div").insert(() => document.createElement("p"));

Which is equivalent to:

d3.selectAll("div").select(function() {
  return this.insertBefore(document.createElement("p"), null);
});

In both cases, this method returns a new selection containing the appended elements. Each new element inherits the data of the current elements, if any, in the same manner as selection.select.

The specified name may have a namespace prefix, such as svg:text to specify a text attribute in the SVG namespace. See namespaces for the map of supported namespaces; additional namespaces can be registered by adding to the map. If no namespace is specified, the namespace will be inherited from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used (for example, svg implies svg:svg).

selection.remove()

Source · Removes the selected elements from the document. Returns this selection (the removed elements) which are now detached from the DOM. There is not currently a dedicated API to add removed elements back to the document; however, you can pass a function to selection.append or selection.insert to re-add elements.

selection.clone(deep)

Source · Inserts clones of the selected elements immediately following the selected elements and returns a selection of the newly added clones. If deep is truthy, the descendant nodes of the selected elements will be cloned as well. Otherwise, only the elements themselves will be cloned. Equivalent to:

selection.select(function() {
  return this.parentNode.insertBefore(this.cloneNode(deep), this.nextSibling);
});

selection.sort(compare)

Source · Returns a new selection that contains a copy of each group in this selection sorted according to the compare function. After sorting, re-inserts elements to match the resulting order (per selection.order).

The compare function, which defaults to ascending, is passed two elements’ data a and b to compare. It should return either a negative, positive, or zero value. If negative, then a should be before b; if positive, then a should be after b; otherwise, a and b are considered equal and the order is arbitrary.

selection.order()

Source · Re-inserts elements into the document such that the document order of each group matches the selection order. This is equivalent to calling selection.sort if the data is already sorted, but much faster.

selection.raise()

Source · Re-inserts each selected element, in order, as the last child of its parent. Equivalent to:

selection.each(function() {
  this.parentNode.appendChild(this);
});

selection.lower()

Source · Re-inserts each selected element, in order, as the first child of its parent. Equivalent to:

selection.each(function() {
  this.parentNode.insertBefore(this, this.parentNode.firstChild);
});

create(name)

Source · Given the specified element name, returns a single-element selection containing a detached element of the given name in the current document. This method assumes the HTML namespace, so you must specify a namespace explicitly when creating SVG or other non-HTML elements; see namespace for details on supported namespace prefixes.

d3.create("svg") // equivalent to svg:svg

d3.create("svg:svg") // more explicitly

d3.create("svg:g") // an SVG G element

d3.create("g") // an HTML G (unknown) element

creator(name)

Source · Given the specified element name, returns a function which creates an element of the given name, assuming that this is the parent element. This method is used internally by selection.append and selection.insert to create new elements. For example, this:

selection.append("div");

Is equivalent to:

selection.append(d3.creator("div"));

See namespace for details on supported namespace prefixes, such as for SVG elements.