Spring Kit

Small spring utilities for motion systems.

keyframes.dev · mosa.sh

Spring Kit solves a damped harmonic oscillator in closed form. It has no runtime dependencies. Under-damped springs overshoot. Critically damped and over-damped springs do not.

npm i spring-kit

import { settleDuration, springProgress } from "spring-kit";

const config = { stiffness: 260, damping: 26, mass: 1 };
springProgress(0.2, config); // progress at t = 0.2s
settleDuration(config); // seconds until it settles within 0.5%

Use dampingRatio and naturalFrequency to inspect a spring. springVelocity is useful when an interaction interrupts an animation.

The solver also accepts initial, target, and initial velocity. fromDurationBounce and toDurationBounce convert between physical settings and design-oriented parameters. sampleTable produces data for charts or exports. thresholdCrossings, peakTime, isAtRest, and overshootCount answer common motion-analysis questions. fitSpring returns a configuration and its RMS approximation error.

toCssLinear samples a spring into a CSS linear() easing. It keeps overshoot and returns the matching duration in milliseconds.

const { easing, duration } = toCssLinear({ stiffness: 260, damping: 18 });
el.style.transition = `transform ${duration}ms ${easing}`;

API

| Export | What it does | | --- | --- | | diagnoseSpring, resolveSpring | Check a configuration or apply defaults and throw on invalid values. | | dampingRatio, naturalFrequency | Read the spring's physical characteristics. | | fromDurationBounce, toDurationBounce | Convert between physical settings and duration plus bounce. Durations are in seconds. | | springValue, springProgress, springVelocity | Read position, normalized progress, or velocity at a time in seconds. | | sampleSpring | Interpolate arbitrary values using spring progress. | | isAtRest, settleDuration | Decide when a spring has settled and find a useful end time. | | thresholdCrossings, overshootCount, peakTime | Inspect target crossings and overshoot. | | sampleTable | Produce evenly spaced position and velocity samples. | | fitSpring | Fit a physical spring to normalized progress samples. | | toCssLinear | Turn a spring into a CSS linear() easing and matching duration. |

Related package

Bezier Kit handles cubic Bézier timing curves. Use it when the animation API expects a CSS-compatible easing curve rather than a simulated spring.