Skip to content

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.

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 × velocity

Position 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.

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.

target0.5 s1 s1.5 s2 s
  • ζ 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.

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π / duration
stiffness = omega²
zeta = 1 - bounce when bounce >= 0
1 / (1 + bounce) when bounce < 0
damping = 2 · zeta · omega

zeta is the damping ratio: below 1 the spring overshoots, at 1 it is critically damped and above 1 it is overdamped.

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.

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.16
console.log(spring.isSettled(0.5)); // false
console.log(spring.isSettled(spring.settleTime())); // true

With 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.

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.

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.

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 device
console.log(stepped(100, 0.5, 60).toFixed(3)); // 100.684
console.log(stepped(100, 0.5, 144).toFixed(3)); // 100.673

Stepping 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) and at(t) work on a spring that nothing is playing.
  • Handover to the browser. The compositor driver samples the same curve into keyframes.

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 turns

animate, 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

or press R

Position

Velocity

  • restart starts again from rest
  • damped keeps its velocity
Velocity of each lane, in lengths per second
LaneNowAt the interruptionRight after
restart0.00 /s––
damped0.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.