Springs explained
A spring animation moves a value toward a target the way a mass on a spring would: fast at first, slowing down as it arrives, optionally overshooting. Unlike an easing curve, a spring has a state, a position and a velocity, and that state is what makes it interruptible. Four figures below let you touch each part of that.
A mass on a spring
Section titled “A mass on a spring”Fix one end of a spring to a wall and hang a mass on the other end. At rest the spring pulls with no force. Pull the mass away and the spring pulls back, harder the further you go. Let go and the mass accelerates toward rest, passes it with some speed, and the spring now pulls the other way.
Drag the mass below and let go. Your hand’s velocity at the release becomes the starting velocity of a damped spring, so a flick travels further than a gentle release. Catch the mass while it swings and it stops where it is; let go again and it continues from that state.
A mass on a spring
Position over the last five seconds. Rest is the line through the middle.
- Position (units)
- 0.0
- Velocity (units/s)
- 0
The mass is at rest. Drag it and let go, or focus it, pull it with the arrow keys and let go with Enter or Space.
It does not swing forever because of friction, which pushes against the velocity. The two forces together give the whole motion:
mass × acceleration = −stiffness × position − damping × velocityPosition is measured from rest. stiffness sets how hard the spring pulls, damping how much friction there is, and mass how reluctant the object is to change speed. Every spring in damped solves this one equation.
Damping
Section titled “Damping”The same spring can behave in three ways, and the damping ratio zeta decides which. It compares the friction with the amount that would stop the mass most quickly without a single swing:
zeta = damping / (2 · sqrt(stiffness · mass))- Below 1, underdamped: the mass overshoots the target and swings back, each swing smaller than the last.
- At 1, critically damped: it returns as fast as it can without overshooting.
- Above 1, overdamped: friction dominates and it creeps in slowly, with no overshoot.
Move the slider to change zeta. The three thin curves are reference values; the bright one is yours, and the ball replays it when you let go. bounce, the option you will use most, describes the same thing: bounce = 1 - zeta while it is positive. Under the plot are the numbers behind the slider: duration is fixed at 0.6 s, so each zeta is a bounce, and springParams turns that pair into a stiffness and a damping for a mass of 1.
Damping ratio
Slide to change how much friction there is. Letting go replays the motion.
- ζ 0.3 underdamped
- ζ 1 critically damped
- ζ 2.0 overdamped
- ζ 0.40 now
- Damping ratio
- 0.40
- Bounce
- 0.60
- Duration
- 0.60 s
- Stiffness
- 109.7
- Damping
- 8.38
- Mass
- 1
- Overshoot
- 25.4 %
- Behavior
- underdamped
Damping ratio 0.40, underdamped. It overshoots the target by 25.4 percent and settles after 1.68 seconds.
Two ways to describe a spring
Section titled “Two ways to describe a spring”Every damped API takes the same options, in one of two forms.
| Perceptual | Physical | |
|---|---|---|
| Options | duration, bounce |
stiffness, damping, mass |
| You say | “About half a second, a little bounce.” | “A spring of this stiffness, this much friction, this heavy.” |
| Defaults | duration: 0.5, bounce: 0.15 |
mass: 1; stiffness and damping have none |
| Selected by | Leaving stiffness out. |
Passing stiffness (and then damping). |
Both describe the same physics. springParams shows the conversion:
import { springParams } from "@damped/core";
// The defaults: duration 0.5, bounce 0.15.console.log(springParams());// { stiffness: 157.91…, damping: 21.36…, mass: 1 }
// No bounce at all: critically damped.console.log(springParams({ duration: 0.5, bounce: 0 }));// { stiffness: 157.91…, damping: 25.13…, mass: 1 }
// The physical form is returned as it is.console.log(springParams({ stiffness: 170, damping: 26, mass: 1 }));The conversion uses a mass of 1:
omega = 2π / durationstiffness = omega²zeta = 1 - bounce when bounce >= 0 1 / (1 + bounce) when bounce < 0damping = 2 · zeta · omegazeta is the damping ratio: below 1 the spring overshoots, at 1 it is critically damped and above 1 it is overdamped.
Which one to use
Section titled “Which one to use”Start with duration and bounce. They describe what you see, and they stay meaningful when you change one of them: halving duration makes the same motion twice as fast without changing its character. Reach for stiffness, damping and mass when:
- you are porting a motion from a library or a design tool that gives you physical values;
- you need a different
mass, for example to make a heavy element lag; - you want to reason about the physics, for instance
zeta = damping / (2 · sqrt(stiffness · mass)).
bounce must be between -1 and 1 (exclusive); invalid values throw a RangeError that names the option.
What duration is not
Section titled “What duration is not”duration is the period of the underlying oscillation, not the time the animation takes to come to rest. A spring approaches its target gradually, so “at rest” needs a definition: damped counts it as settled once it is within restDelta of the target and slower than restSpeed. settleTime() tells you when that happens.
import { createSpring } from "@damped/core";
const spring = createSpring(0, 100, 0, { duration: 0.5, bounce: 0.15 });
console.log(spring.settleTime().toFixed(2)); // 1.16console.log(spring.isSettled(0.5)); // falseconsole.log(spring.isSettled(spring.settleTime())); // trueWith the defaults a 100-unit move settles in about 1.16 s through createSpring. animate uses coarser thresholds suited to pixels (0.01 px, 0.1 px/s), so the same move through animate({ x: 100 }) rests at 0.94 s. The last digits of a spring’s tail are invisible, and stopping there saves frames.
How bounce feels
Section titled “How bounce feels”The overshoot depends only on the damping ratio, so it is the same for any duration. The settle times below are for a 100 px move through animate at duration: 0.5; they grow roughly in proportion to duration.
bounce |
zeta |
Peak overshoot | Settles after | Feel |
|---|---|---|---|---|
-0.5 |
2.00 | none | 2.78 s | Heavy and slow, creeps in with no overshoot. |
0 |
1.00 | none | 0.95 s | Fastest approach without overshoot. |
0.15 (default) |
0.85 | 0.63 % | 0.94 s | Settles with a barely visible give. |
0.3 |
0.70 | 4.6 % | 1.11 s | Visibly springy. |
0.5 |
0.50 | 16.3 % | 1.53 s | Playful, wobbles before it rests. |
The phase portrait
Section titled “The phase portrait”Plot position against time and you get the curves above. Plot position against velocity instead and time disappears into the path: the state of the spring, { position, velocity }, becomes one point on a plane, and the motion is that point moving.
For an underdamped spring the point does not go straight home. The mass swings out, slows, stops for an instant at the far end (velocity zero, so the point crosses the position axis), swings back through rest at full speed (position zero, so it crosses the velocity axis) and each lap is smaller than the last. The path is a spiral that winds into the rest point. This is the shape of the damped mark: one winding of this curve and the dot it comes to rest on.
Drag the dot to any point on the plane and let go. The spring starts from exactly that state and draws its path. Try a point with some velocity and no displacement, then raise zeta past 1 and watch the spiral unwind into a plain curve.
The phase portrait
Drag the dot anywhere on the plane, or focus it and use the arrow keys, then let go (Enter or Space). Pull and release starts from the edge, Kick from the middle with a push.
- Position
- 0.00
- Velocity (per s)
- 0.00
- Damping ratio
- 0.25
- Path
- spiral
The state is a point: position across, velocity up. Drag it, then let go.
Since the state is a point, everything the spring needs to continue is those two numbers. A new target moves the rest point and nothing else: the position and the velocity stay what they were, and the path now winds toward the new rest. That is why an interruption can carry on from exactly where the motion was.
Analytic: the exact state at any time
Section titled “Analytic: the exact state at any time”Many animation engines advance a spring by stepping: each frame adds a small change to the position and velocity. That is an approximation, and the result depends on the frame rate. damped solves the spring equation in closed form, so for any time t it can compute the exact position and velocity directly, for underdamped, critically damped and overdamped springs alike.
import { createSpring, springParams } from "@damped/core";
const options = { duration: 0.5, bounce: 0.15 } as const;const { stiffness, damping, mass } = springParams(options);
// Explicit Euler: add acceleration × step each frame.function stepped(target: number, seconds: number, hz: number): number { const dt = 1 / hz; let position = 0; let velocity = 0; for (let frame = 0; frame < Math.round(seconds * hz); frame++) { const acceleration = (stiffness * (target - position) - damping * velocity) / mass; position += velocity * dt; velocity += acceleration * dt; } return position;}
const exact = createSpring(0, 100, 0, options).at(0.5).position;
console.log(exact.toFixed(3)); // 100.602, the same on every deviceconsole.log(stepped(100, 0.5, 60).toFixed(3)); // 100.684console.log(stepped(100, 0.5, 144).toFixed(3)); // 100.673Stepping gives a different answer at 60 Hz and at 144 Hz, and neither is the true one. Evaluating the closed form gives the same state whatever frames came before. In damped’s tests the state of an animation after a given time is identical at 60 Hz, at 144 Hz and at an irregular frame cadence, to within 1e-12, while an explicit Euler control diverges by more than 1e-3.
What that buys you:
- Frame-rate independence. A 120 Hz display, a 60 Hz one and a laggy tab all draw points on the same curve.
- Hitches do not distort the motion. A 2 s stall is not clamped or smoothed: the next frame simply evaluates the curve at the new time.
- You can ask questions without animating.
settleTime(),isSettled(t)andat(t)work on a spring that nothing is playing. - Handover to the browser. The compositor driver samples the same curve into keyframes.
Velocity continuity
Section titled “Velocity continuity”A spring’s state is { position, velocity }. When the target changes while it is moving, the new spring must start from that state, or the motion visibly jerks.
import { createSpring } from "@damped/core";
const options = { duration: 0.5, bounce: 0.15 } as const;
// Heading to 100, interrupted 200 ms in.const first = createSpring(0, 100, 0, options);const { position, velocity } = first.at(0.2);console.log(position.toFixed(1), velocity.toFixed(1)); // 78.6 273.2
// The new target is 0, but the element is still moving forward at 273 units per second.const second = createSpring(position, 0, velocity, options);console.log(second.at(0.02).position.toFixed(1)); // 80.9: it keeps going forward for a moment, then turnsanimate, createSpringValue, layout, morph and the React hooks do this for you on every retarget.
An easing curve such as ease-out has no velocity to carry. Interrupt it and the new animation starts from rest, so the motion stalls and restarts. The figure below runs both from the same state. The lanes are identical springs; the only difference is what happens at a retarget. The damped lane calls set() on the value again. The restart lane does what an easing curve does: it jumps to the position the value had, which drops its velocity, and starts a new spring from rest. Press the button, then press it again while the balls are moving. Each press moves the target one stop further right, and the third sends it back to the start. Compare the velocities and the traces.
Interrupting a spring
Position
Velocity
- restart starts again from rest
- damped keeps its velocity
| Lane | Now | At the interruption | Right after |
|---|---|---|---|
| restart | 0.00 /s | – | – |
| damped | 0.00 /s | – | – |
Both lanes are at rest. Press the button, then press it again while they move.
The velocity plot shows it most clearly. At each retarget the restart line drops to zero and climbs again, which is the stall you see as a flat spot in its position trace, while the damped line goes on without a jump. Interruption and reversal goes through what that looks like and how damped handles reversals of layout, morph and presence.