tessl/npm-d3-transition

Animated transitions for D3 selections with smooth interpolation between DOM states over time.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Transition Creation

Name: tessl/npm-d3-transition
Author: tessl

Core functions for creating and managing transitions from selections or directly from the document root element.

Capabilities

transition Function

Creates a new transition on the document root element. This is equivalent to calling d3.selection().transition(name).

/**
 * Creates a new transition on the document root element
 * @param name - Optional name for the transition (string) or existing transition to synchronize with
 * @returns New Transition instance
 */
function transition(name?: string | Transition): Transition;

Usage Examples:

import { transition } from "d3-transition";

// Create unnamed transition
const t1 = transition();

// Create named transition
const t2 = transition("fade");

// Synchronize with existing transition
const t3 = transition(t1);

// Apply to elements
transition()
  .duration(1000)
  .ease(d3.easeLinear)
  .selectAll("circle")
  .attr("r", 10);

selection.transition Method

Creates a transition from a d3-selection. This method is added to the selection prototype when d3-transition is imported.

/**
 * Creates a transition from a selection
 * @param name - Optional name for the transition (string) or existing transition to synchronize with
 * @returns New Transition instance on the selected elements
 */
selection.transition(name?: string | Transition): Transition;

Usage Examples:

import { select, selectAll } from "d3-selection";
import "d3-transition";

// Transition on single element
select("body")
  .transition()
  .style("background-color", "blue");

// Transition on multiple elements
selectAll("div")
  .transition("slide")
  .duration(500)
  .style("transform", "translateX(100px)");

// Synchronized transitions
const t = select("svg").transition().duration(1000);

select(".group1").transition(t)
  .attr("opacity", 0.5);

select(".group2").transition(t)
  .attr("fill", "red");

active Function

Returns the active transition on a specified DOM node, if any. Useful for creating chained transitions or checking transition state.

/**
 * Returns the active transition on the specified node
 * @param node - DOM element to check for active transitions
 * @param name - Optional transition name to look for
 * @returns Active Transition instance or null if none found
 */
function active(node: Element, name?: string): Transition | null;

Usage Examples:

import { active } from "d3-transition";

// Check for active transition
const element = document.querySelector("circle");
const activeTransition = active(element);

if (activeTransition) {
  // Chain another transition
  activeTransition
    .transition()
    .attr("fill", "green");
}

// Check for named transition
const namedTransition = active(element, "pulse");

// Common pattern: disco mode animation
selectAll("circle").transition()
  .delay((d, i) => i * 50)
  .on("start", function repeat() {
    active(this)
      .style("fill", "red")
      .transition()
      .style("fill", "green")  
      .transition()
      .style("fill", "blue")
      .transition()
      .on("start", repeat);
  });

interrupt Function

Interrupts active transitions and cancels pending transitions on a specified DOM node.

/**
 * Interrupts active and cancels pending transitions on a node
 * @param node - DOM element to interrupt transitions on
 * @param name - Optional transition name to interrupt (null interrupts unnamed transitions)
 * @returns void
 */
function interrupt(node: Element, name?: string): void;

Usage Examples:

import { interrupt } from "d3-transition";

// Interrupt all unnamed transitions on element
const element = document.querySelector("circle");
interrupt(element);

// Interrupt named transition
interrupt(element, "pulse");

// Interrupt all transitions (including named ones)
interrupt(element, null); // unnamed
interrupt(element, "pulse"); // named transition

selection.interrupt Method

Interrupts transitions on all selected elements. This method is added to the selection prototype when d3-transition is imported.

/**
 * Interrupts transitions on all selected elements
 * @param name - Optional transition name to interrupt
 * @returns The selection (for method chaining)
 */
selection.interrupt(name?: string): Selection;

Usage Examples:

import { selectAll } from "d3-selection";
import "d3-transition";

// Interrupt all unnamed transitions on selection
selectAll("circle").interrupt();

// Interrupt named transitions
selectAll(".animated").interrupt("fade");

// Interrupt transitions on descendants (common for complex components like axes)
selection.selectAll("*").interrupt();

// Interrupt both parent and descendants
selection.interrupt().selectAll("*").interrupt();

Transition Names and Synchronization

Transitions can be named to allow multiple concurrent animations on the same elements. Only transitions with the same name are mutually exclusive.

// These transitions can run concurrently
select("circle")
  .transition("color")
  .attr("fill", "red");
  
select("circle")
  .transition("size")  
  .attr("r", 20);

// This will interrupt the previous "color" transition
select("circle")
  .transition("color")
  .attr("fill", "blue");

When passing an existing transition as the name parameter, the new transition inherits timing and synchronization:

const masterTransition = transition()
  .duration(1000)
  .ease(d3.easeLinear);

// Both transitions will be synchronized
selectAll(".item1").transition(masterTransition)
  .attr("x", 100);
  
selectAll(".item2").transition(masterTransition)
  .attr("y", 100);

Install with Tessl CLI