d3-interpolate

d3-interpolate is the interpolation engine that powers smooth transitions across the D3.js ecosystem. It generates functions that blend between two values of the same type — numbers, RGB/HSL/Lab/HCL/Cubehelix colors, arbitrary strings containing embedded numbers, arrays, and deeply nested objects — returning a single function that computes any point along that continuum for a parameter t between 0 and 1.

Beyond basic value blending, the library includes specialized interpolators for common visualization needs: zoom interpolation using Van Wijk’s optimal path algorithm for smooth pan-and-zoom transitions, CSS/SVG transform interpolation that decomposes affine matrices into translate/rotate/skewX/scale components, and quantize/piecewise helpers for building discrete color scales or multi-stop gradients.

What You Get

• Type-dispatching interpolate() that auto-selects the right strategy for numbers, colors, strings, arrays, dates, and objects
• A full family of color-space interpolators (RGB, HSL, Lab, HCL, Cubehelix) including “long path” hue variants
• interpolateString for blending strings with embedded numbers (e.g. “10px” to “20px”) while preserving surrounding text
• interpolateZoom implementing Van Wijk’s smooth zooming algorithm for pan/zoom transitions
• interpolateTransformCss / interpolateTransformSvg for animating CSS and SVG transform matrices
• quantize and piecewise helpers for sampling interpolators into discrete steps or chaining multiple keyframes

Common Use Cases

• Animating chart axis/scale transitions when data updates in a D3 visualization
• Building smooth color gradients or legends by interpolating across a color space
• Powering pan-and-zoom interactions in map or network visualizations
• Tweening CSS/SVG transform properties during element enter/update/exit transitions

Under The Hood

Architecture The library is a flat collection of ~20 single-purpose ES modules re-exported from src/index.js: value.js implements the top-level interpolate() dispatcher that inspects the type of its target argument and delegates to number.js, string.js, rgb.js, date.js, object.js, or array.js; the color interpolators (rgb.js, hsl.js, lab.js, hcl.js, cubehelix.js) each wrap a d3-color color-space converter around a shared gamma-correction closure factory in color.js; and transform/{parse,decompose,index}.js implement CSS/SVG affine-matrix decomposition feeding a generic transform-interpolation closure. There are no classes — every interpolator is a factory function returning a plain closure over t. Because value.js’s dispatch logic is the entry point every consumer (d3-scale, d3-transition, and applications) calls through interpolate(), it is the module with the widest blast radius if its type-detection logic changes.

Tech Stack The package is pure ESM ("type": "module") with a single runtime dependency, d3-color (accepting versions 1 through 3). Development tooling is minimal and dated relative to current JS tooling: ESLint 7 for linting, Mocha 8 for tests, and Rollup 2 with rollup-plugin-terser for producing UMD and minified bundles published to jsdelivr/unpkg via rollup.config.js. No TypeScript is used in the source; the package targets Node >=12 and ships both an ESM entry (src/index.js) and a prebuilt UMD bundle.

Code Quality Test coverage is broad relative to the module’s surface area — 23 *-test.js files under test/, one per interpolator (plus “Long” hue-path variants for HSL/HCL/Cubehelix), using Mocha with Node’s built-in assert plus a custom assertInDelta helper for floating-point tolerance. A GitHub Actions workflow runs ESLint and the full Mocha suite on Node 14 for every push and PR. Code style favors terse, closure-heavy ES5/ES6 hybrid syntax (var, single quotes) with no type annotations and no explicit input validation — functions largely rely on duck-typing and coercion rather than throwing on bad input.

API Design The public API is highly consistent: every specialized interpolator follows the interpolateX naming convention and is a single default export taking (a, b) and returning a t => value function, so there is effectively zero setup boilerplate — import and call. The generic interpolate() entry point removes the need to pick a specific function for the common case, while explicit named exports (interpolateRgb, interpolateHcl, etc.) are available when a caller needs to force a specific type. The “Long” hue-path suffix for color interpolators (interpolateHslLong, interpolateHclLong) is the one naming choice that isn’t self-explanatory without reading the docs. No TypeScript types ship with the package itself (community @types/d3-interpolate definitions exist separately).