Transition methods paralleling selection methods
Transitions support most selection methods such as transition.attr and transition.style in place of selection.attr and selection.style, but not all methods are supported.
d3-transition
52 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Operations that must happen before transition starts
You must append elements or bind data before a transition starts. Transitions do not support these operations directly.
transition.remove() operator for element removal
A transition.remove() operator is provided for convenient removal of elements when the transition ends.
Automatic interpolation in transitions
Transitions leverage built-in interpolators to compute intermediate state. Colors, numbers, and transforms are automatically detected. Strings with embedded numbers are also detected, as is common with many styles such as padding or font sizes and paths.
Custom interpolators in transitions
To specify a custom interpolator, use transition.attrTween, transition.styleTween, or transition.tween.
Transition is a selection-like interface for DOM animation
A transition is a selection-like interface for animating changes to the DOM. Instead of applying changes instantaneously, transitions smoothly interpolate the DOM from its current state to the desired target state over a given duration.
Basic transition workflow
To apply a transition, select elements, call selection.transition(), and then make the desired changes. For example, d3.select('body').transition().style('background-color', 'red') will smoothly animate the background color to red.
transition.tween example
Example: interpolate the fill attribute to blue using a custom tween: ```js transition.tween("attr.fill", function() { const i = d3.interpolateRgb(this.getAttribute("fill"), "blue"); return function(t) { this.setAttribute("fill", i(t)); }; }); ```
transition.attr signature and interpolation
transition.attr(name, value) assigns an attribute tween for the specified attribute name to the target value. The value may be a constant or function. If a function, it is evaluated for each selected element in order with parameters (d, i, nodes) and this as the current DOM element. If value is null, the attribute is removed when the transition starts. Interpolator selection: if value is a number, uses interpolateNumber; if value is a color or string coercible to a color, uses interpolateRgb; otherwise uses interpolateString. Use transition.attrTween for a different interpolator.
transition.styleTween signature and factory
transition.styleTween(name, factory, priority) assigns a style tween for the specified style name to the specified interpolator factory. Factory is a function that returns an interpolator; when the transition starts, factory is evaluated for each selected element in order with parameters (d, i, nodes) and this as the current DOM element. The returned interpolator is invoked for each frame with eased time t (typically 0 to 1 range) and must return a string. The returned value is used to set the style with specified priority. If factory is null, removes the previously-assigned style tween. If factory is not specified, returns the current interpolator factory or undefined.
transition.style signature and interpolation
transition.style(name, value, priority) assigns a style tween for the specified style name to the target value with specified priority. The value may be a constant or function. If a function, it is evaluated for each selected element in order with parameters (d, i, nodes) and this as the current DOM element. The starting value is the style's inline value if present, otherwise its computed value. If value is null, the style is removed when the transition starts. Interpolator selection: if value is a number, uses interpolateNumber; if value is a color or string coercible to a color, uses interpolateRgb; otherwise uses interpolateString. Use transition.styleTween for a different interpolator.
transition.styleTween examples
Example 1: interpolate fill style from red to blue: ```js transition.styleTween("fill", () => d3.interpolateRgb("red", "blue")); ``` Example 2: interpolate from current fill to blue: ```js transition.styleTween("fill", function() { return d3.interpolateRgb(this.style.fill, "blue"); }); ``` Example 3: custom rainbow interpolator: ```js transition.styleTween("fill", () => (t) => `hsl(${t * 360},100%,50%)`); ```
transition.text signature and behavior
transition.text(value) sets the text content to the specified target value when the transition starts. The value may be a constant or function. If a function, it is evaluated for each selected element in order with parameters (d, i, nodes) and this as the current DOM element. The function's return value is used to set each element's text content. A null value clears the content. Text is not interpolated by default because it is usually undesirable; use transition.textTween or append a replacement element and cross-fade opacity instead.
transition.textTween signature and factory
transition.textTween(factory) assigns a text tween to the specified interpolator factory. Factory is a function that returns an interpolator; when the transition starts, factory is evaluated for each selected element in order with parameters d and i, with this as the current DOM element. The returned interpolator is invoked for each frame with eased time t (typically 0 to 1 range) and must return a string used to set the text. If factory is null, removes the previously-assigned text tween. If factory is not specified, returns the current interpolator factory or undefined.
transition.textTween example
Example: interpolate text with integers from 0 to 100: ```js transition.textTween(() => d3.interpolateRound(0, 100)); ```
transition.remove signature and behavior
transition.remove() removes each selected element when the transition ends, as long as the element has no other active or pending transitions. If the element has other active or pending transitions, does nothing.
transition.tween signature and factory
transition.tween(name, value) assigns a tween with the specified name to the value function for each selected element. The value must be specified as a function that returns a function. When the transition starts, the value function is evaluated for each selected element in order with parameters (d, i, nodes) and this as the current DOM element. The returned function is invoked for each frame with eased time t (typically 0 to 1 range). If value is null, removes the previously-assigned tween of the specified name.
interrupt(node, name) signature and behavior
Interrupts the active transition of the specified name on the specified node, and cancels any pending transitions with the specified name, if any. If a name is not specified, null is used.
Transition lifecycle: scheduling phase
Shortly after creation, either at the end of the current frame or during the next frame, the transition is scheduled. At this point, the delay and start event listeners may no longer be changed. Attempting to do so throws an error with the message 'too late: already scheduled' or 'transition not found' if the transition has ended.
Transition lifecycle: start phase and interrupts
When a transition starts, it interrupts the active transition of the same name on the same element, if any, dispatching an interrupt event. Interrupts happen on start, not creation, so even a zero-delay transition will not immediately interrupt the active transition; the old transition is given a final frame. The starting transition cancels any pending transitions of the same name on the same element that were created before it, then dispatches a start event. The transition's timing, tweens, and listeners may not be changed when it is running; attempting to do so throws an error with the message 'too late: already running' or 'transition not found' if the transition has ended. Tweens are initialized immediately after starting.
Transition lifecycle: active phase
During each frame that a transition is active, it invokes its tweens with an eased t-value ranging from 0 to 1. Batching tween initialization after all transitions have started improves performance by avoiding interleaved DOM reads and writes. Within each frame, the transition invokes its tweens in the order they were registered.
Transition lifecycle: end phase
When a transition ends, it invokes its tweens a final time with a non-eased t-value of 1, then dispatches an end event to registered listeners. After ending, the transition is deleted from the element and its configuration is destroyed. A transition's configuration is also destroyed on interrupt or cancel. Attempting to inspect a transition after it is destroyed throws an error with the message 'transition not found'.
selection.interrupt(name) signature and behavior
Interrupts the active transition of the specified name on the selected elements, and cancels any pending transitions with the specified name. If a name is not specified, null is used. Interrupting a transition on an element has no effect on any transitions on descendant elements. To interrupt an axis transition, which consists of multiple independent, synchronized transitions on the descendants of the axis G element, you must interrupt the descendants using selection.selectAll('*').interrupt(). To interrupt both the G element and its descendants, use selection.interrupt().selectAll('*').interrupt().
Transition lifecycle: configuration phase
After creating a transition via selection.transition() or transition.transition(), you may configure it using methods like transition.delay(), transition.duration(), transition.attr() and transition.style(). Methods that specify target values are evaluated synchronously. Methods that require the starting value for interpolation, such as transition.attrTween() and transition.styleTween(), must be deferred until the transition starts.
transition.end() returns promise
Returns a promise that resolves when every selected element finishes transitioning. If any element's transition is cancelled or interrupted, the promise rejects.
transition.on(typenames, listener) event types
Adds or removes a listener to each selected element for the specified event typenames. The supported event types are: start (when the transition starts), end (when the transition ends), interrupt (when the transition is interrupted), and cancel (when the transition is cancelled). These are transition events, not native DOM events.
transition.on() typename format and multiple callbacks
The type may be optionally followed by a period (.) and a name to allow multiple callbacks to be registered to receive events of the same type, such as start.foo and start.bar. To specify multiple typenames, separate typenames with spaces, such as 'interrupt end' or 'start.foo start.bar'. To remove a listener, pass null as the listener. To remove all listeners for a given name, pass null as the listener and .foo as the typename. To remove all listeners with no name, specify . as the typename.
transition.on() listener context and arguments
When a specified transition event is dispatched on a selected node, the specified listener will be invoked for the transitioning element, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. Listeners always see the latest datum for their element, but the index is a property of the selection and is fixed when the listener is assigned; to update the index, re-assign the listener.
transition.on() getter behavior
If a listener is not specified, returns the currently-assigned listener for the specified event typename on the first (non-null) selected element, if any. If multiple typenames are specified, the first matching listener is returned.
transition.each(function) signature and behavior
Invokes the specified function for each selected element, passing in the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. This method can be used to invoke arbitrary code for each selected element and is useful for creating a context to access parent and child data simultaneously. Equivalent to selection.each().
transition.call(function, ...arguments) example
Invokes the specified function exactly once, passing in this transition along with any optional arguments. Returns this transition. Example: define a function to set multiple styles: function color(transition, fill, stroke) { transition.style('fill', fill).style('stroke', stroke); } Then call it on a transition: d3.selectAll('div').transition().call(color, 'red', 'blue'); This is equivalent to: color(d3.selectAll('div').transition(), 'red', 'blue');
transition.empty() returns boolean
Returns true if this transition contains no (non-null) elements. Equivalent to selection.empty().
transition.nodes() returns array of elements
Returns an array of all (non-null) elements in this transition. Equivalent to selection.nodes().
transition.node() returns first element or null
Returns the first (non-null) element in this transition. If the transition is empty, returns null. Equivalent to selection.node().
transition.size() returns element count
Returns the total number of elements in this transition. Equivalent to selection.size().
transition.easeVarying() example with per-element easing
Using transition.easeVarying((d) => d3.easePolyIn.exponent(d.exponent)) applies a polynomial easing function with exponent varying per element based on the datum's exponent property.
transition.ease() signature and behavior
transition.ease(value) specifies the easing function for all selected elements. The value must be a function that takes normalized time t in the range [0, 1] and returns eased time t' typically also in the range [0, 1]. A good easing function returns 0 when t = 0 and 1 when t = 1. If not specified, the default easing function is easeCubic. When called without arguments, returns the current easing function for the first non-null element in the transition.
transition.delay() signature and behavior
transition.delay(value) sets the transition delay for each selected element in milliseconds. The value may be a constant or a function. If a function, it is immediately evaluated for each selected element in order, receiving the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function's return value sets each element's transition delay. If not specified, delay defaults to zero. When called without arguments, returns the current delay for the first non-null element in the transition.
transition.delay() example with index-based staggering
Using transition.delay((d, i) => i * 10) stagers transitions across elements by multiplying the index by 10 milliseconds for each element.
transition.duration() signature and behavior
transition.duration(value) sets the transition duration for each selected element in milliseconds. The value may be a constant or a function. If a function, it is immediately evaluated for each selected element in order, receiving the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The function's return value sets each element's transition duration. If not specified, duration defaults to 250 milliseconds. When called without arguments, returns the current duration for the first non-null element in the transition.
transition.easeVarying() signature and behavior
transition.easeVarying(factory) specifies a factory function for the transition easing function. The factory must be a function invoked for each node of the selection, receiving the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element. The factory must return an easing function.
transition.selectChildren(selector) signature and behavior
transition.selectChildren(selector) for each selected element selects all children that match the specified selector string, if any, and returns a transition on the resulting selection. The selector may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.
transition.filter(filter) signature and behavior
transition.filter(filter) for each selected element selects only the elements that match the specified filter, and returns a transition on the resulting selection. The filter may be specified either as a selector string or a function. If 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. The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element.
transition.merge(other) signature and behavior
transition.merge(other) returns a new transition merging this transition with the specified other transition, which must have the same id as this transition. The returned transition has the same number of groups, the same parents, the same name and the same id as this transition. Any missing (null) elements in this transition are filled with the corresponding element, if present (not null), from the other transition.
transition.transition() signature and behavior
transition.transition() returns a new transition on the same selected elements as this transition, scheduled to start when this transition ends. The new transition inherits a reference time equal to this transition's time plus its delay and duration. The new transition also inherits this transition's name, duration, and easing. This method can be used to schedule a sequence of chained transitions. The delay for each transition is relative to its previous transition.
active(node, name) signature and behavior
active(node, name) returns the active transition on the specified node with the specified name, if any. If no name is specified, null is used. Returns null if there is no such active transition on the specified node. This method is useful for creating chained transitions.
transition.selection() signature and behavior
transition.selection() returns the selection corresponding to this transition.
Synchronizing transitions across multiple selections example
This example shows how to use a transition instance as the name parameter to synchronize transitions across multiple selections: const t = d3.transition() .duration(750) .ease(d3.easeLinear); d3.selectAll(".apple").transition(t) .style("fill", "red"); d3.selectAll(".orange").transition(t) .style("fill", "orange");
Chained transitions using active() example
This example shows how to use active() to create chained transitions initiated from within a transition's start event: d3.selectAll("circle").transition() .delay((d, i) => i * 50) .on("start", function repeat() { d3.active(this) .style("fill", "red") .transition() .style("fill", "green") .transition() .style("fill", "blue") .transition() .on("start", repeat); });
selection.transition(name) signature and behavior
selection.transition(name) returns a new transition on the given selection with the specified name. If name is not specified, null is used. The new transition is only exclusive with other transitions of the same name. If name is a transition instance, the returned transition has the same id and name as the specified transition. If a transition with the same id already exists on a selected element, the existing transition is returned for that element. Otherwise, the timing of the returned transition is inherited from the existing transition of the same id on the nearest ancestor of each selected element. This method can be used to synchronize a transition across multiple selections or to re-select a transition for specific elements and modify its configuration.
d3.transition(name) signature and behavior
d3.transition(name) returns a new transition on the root element, document.documentElement, with the specified name. If name is not specified, null is used. The new transition is only exclusive with other transitions of the same name. The name may also be a transition instance. This method is equivalent to d3.selection().transition(name). This function can also be used to test for transitions (instanceof d3.transition) or to extend the transition prototype.
Chained transitions example
This example shows how to chain transitions using transition.transition(): d3.selectAll(".apple") .transition() // First fade to green. .style("fill", "green") .transition() // Then red. .style("fill", "red") .transition() // Wait one second. Then brown, and remove. .delay(1000) .style("fill", "brown") .remove();