Core interpolators for primitive data types including numbers, strings, and dates.
Linear interpolation between two numbers.
/**
* Returns an interpolator between the two numbers a and b.
* Equivalent to: function(t) { return a * (1 - t) + b * t; }
* @param a - Starting number
* @param b - Ending number
* @returns Interpolator function returning interpolated number
*/
function interpolateNumber(a: number, b: number): (t: number) => number;Usage Examples:
import { interpolateNumber } from "d3-interpolate";
const interp = interpolateNumber(10, 20);
console.log(interp(0.0)); // 10
console.log(interp(0.2)); // 12
console.log(interp(0.5)); // 15
console.log(interp(1.0)); // 20
// Works with negative numbers
const negInterp = interpolateNumber(-5, 5);
console.log(negInterp(0.5)); // 0
// Works with decimal numbers
const decimalInterp = interpolateNumber(1.5, 2.5);
console.log(decimalInterp(0.5)); // 2.0Caution: Avoid interpolating to or from zero when the result will be stringified, as very small values may be converted to scientific notation (e.g., 1e-7), which is invalid in CSS. Use 1e-6 as the minimum value to avoid scientific notation.
Number interpolation with automatic rounding to nearest integer.
/**
* Returns an interpolator between two numbers that rounds to nearest integer.
* Similar to interpolateNumber but rounds the result.
* @param a - Starting number
* @param b - Ending number
* @returns Interpolator function returning rounded integer
*/
function interpolateRound(a: number, b: number): (t: number) => number;Usage Examples:
import { interpolateRound } from "d3-interpolate";
const roundInterp = interpolateRound(10, 20);
console.log(roundInterp(0.1)); // 11
console.log(roundInterp(0.3)); // 13
console.log(roundInterp(0.7)); // 17
console.log(roundInterp(0.9)); // 19
// Useful for pixel values or indices
const pixelInterp = interpolateRound(0, 100);
console.log(pixelInterp(0.333)); // 33 (rounded from 33.3)Interpolation between strings with embedded number detection.
/**
* Returns an interpolator between two strings with embedded number interpolation.
* Detects numbers within strings and interpolates them while keeping static parts.
* @param a - Starting string
* @param b - Ending string (template)
* @returns Interpolator function returning interpolated string
*/
function interpolateString(a: string, b: string): (t: number) => string;Number Detection:
The interpolator finds numbers embedded in both strings, including:
-1, 423.141596.0221413e+23Usage Examples:
import { interpolateString } from "d3-interpolate";
// CSS property interpolation
const cssInterp = interpolateString("300 12px sans-serif", "500 36px Comic-Sans");
console.log(cssInterp(0.0)); // "300 12px sans-serif"
console.log(cssInterp(0.5)); // "400 24px Comic-Sans"
console.log(cssInterp(1.0)); // "500 36px Comic-Sans"
// Multiple numbers in string
const multiInterp = interpolateString("M10,20 L30,40", "M50,60 L70,80");
console.log(multiInterp(0.5)); // "M30,40 L50,60"
// Percentage values
const percentInterp = interpolateString("width: 10%", "width: 90%");
console.log(percentInterp(0.5)); // "width: 50%"
// No matching numbers (returns template)
const noMatchInterp = interpolateString("foo", "bar");
console.log(noMatchInterp(0.5)); // "bar"
// Scientific notation
const sciInterp = interpolateString("1e-6", "1e-3");
console.log(sciInterp(0.5)); // "0.0005005" (approximately)Linear interpolation between Date objects.
/**
* Returns an interpolator between two Date objects.
* Interpolates the underlying timestamp values.
* @param a - Starting Date
* @param b - Ending Date
* @returns Interpolator function returning Date object
*/
function interpolateDate(a: Date, b: Date): (t: number) => Date;Performance Note: No defensive copy is created; the same Date instance is returned for every evaluation. This is optimized for performance in animation loops but means the returned Date should not be mutated.
Usage Examples:
import { interpolateDate } from "d3-interpolate";
const startDate = new Date(2020, 0, 1); // January 1, 2020
const endDate = new Date(2021, 0, 1); // January 1, 2021
const dateInterp = interpolateDate(startDate, endDate);
console.log(dateInterp(0.0)); // January 1, 2020
console.log(dateInterp(0.5)); // ~July 2, 2020 (mid-year)
console.log(dateInterp(1.0)); // January 1, 2021
// Time-of-day interpolation
const morning = new Date(2023, 5, 15, 9, 0, 0); // 9:00 AM
const evening = new Date(2023, 5, 15, 17, 0, 0); // 5:00 PM
const timeInterp = interpolateDate(morning, evening);
console.log(timeInterp(0.5)); // 1:00 PM same day
// Cross-timezone interpolation (works with timestamps)
const utcStart = new Date("2023-01-01T00:00:00Z");
const utcEnd = new Date("2023-01-02T00:00:00Z");
const utcInterp = interpolateDate(utcStart, utcEnd);
console.log(utcInterp(0.5)); // Noon on January 1, 2023 UTC