useSpring
Animates a number toward a target with a basic damped spring simulation.
About
useSpring returns a number that moves toward a target using stiffness, damping, mass, and precision settings. Unlike duration-based easing, a spring can overshoot before settling.
Examples
import { useState } from "react";
import { usePrefersReducedMotion, useSpring } from "rooks";
export default function SpringValue() {
const [target, setTarget] = useState(0);
const reduceMotion = usePrefersReducedMotion();
const animated = useSpring(target, reduceMotion ? { precision: 1000 } : {});
return (
<section>
<p>Current value: {animated.toFixed(1)}</p>
<button
type="button"
onClick={() => setTarget((value) => (value ? 0 : 100))}
>
Change target
</button>
</section>
);
}Parameters
| Argument | Type | Default | Meaning |
|---|---|---|---|
targetValue | number | required | Value the simulation approaches. |
config.stiffness | number | 170 | Strength pulling toward the target. |
config.damping | number | 26 | Opposes current velocity. |
config.mass | number | 1 | Divides acceleration; use a positive nonzero value. |
config.precision | number | 0.01 | Distance and velocity threshold used to snap to target. |
The configuration shape is shown inline because it is not a public type export.
Return value
A number, initialized to the first target value and updated on animation frames.
Behavior and lifecycle
The simulation uses a fixed 1 / 60 time step rather than the actual frame interval. Target changes preserve velocity. Configuration changes affect later frames but do not restart the spring. When distance and velocity are below precision, the value snaps to the target; the underlying frame loop nevertheless remains active until unmount because callback return values do not stop useRaf.
Compatibility and accessibility
Server output is the initial target. The hook does not automatically honor reduced motion; choose an immediate/static presentation when requested. Do not convey state only through position or movement, and avoid spring settings that flash or oscillate excessively.