React Spring Core: useSpring Hook

Traditional CSS animations use a fixed duration: the animation plays over X milliseconds and stops. react-spring animates values using spring physics — the animation is driven by tension (stiffness of the spring) and friction (how much the spring resists motion). This produces naturally decelerating, organic-feeling movement.

The useSpring({ from, to }) hook defines an animated value. You specify starting values in from and target values in to. useSpring returns a springs object where each key is a SpringValue — an animated version of the corresponding numeric or color value.

The config option controls spring behavior. tension (default 170) controls stiffness — higher values snap faster. friction (default 26) controls damping — lower values bounce more. mass (default 1) adds inertia. These three values together define the character of the animation.

react-spring ships with preset configs you can use without tuning: config.default is balanced and general-purpose, config.gentle is slow and smooth, config.wobbly bounces with low friction, config.stiff is fast and snappy, and config.slow is very gradual. Import them from react-spring.

The values returned by useSpring are SpringValue objects, not regular numbers. You cannot render them directly in JSX or use them in regular style objects. They must be applied to animated.* components which know how to subscribe to spring updates and apply them to the DOM efficiently.

Passing immediate: true to useSpring makes the values jump to their target instantly, bypassing the spring animation. This is useful for initial render, when a user has enabled "reduce motion" in their OS settings, or when you need to programmatically reset position without any visual motion.

You can reverse a spring animation by toggling which values are in from and to. A common pattern is to store a boolean toggle state and compute from/to based on it: when toggle is false, animate from 0 to 1; when true, animate from 1 to 0. react-spring smoothly transitions between states.

useSpring can return a two-element array: const [springs, api] = useSpring(() => ({ from: { x: 0 } })). The api object gives you programmatic control. Call api.start({ x: 100 }) to animate to a new value, api.stop() to freeze the animation, and api.set({ x: 50 }) to jump without animation.

Use the declarative form useSpring({ from, to }) when the animation depends on React state that changes normally. Use the imperative form with api.start() when you need to trigger animations from event handlers, gestures, or async operations without causing React re-renders.

useSpring accepts lifecycle callbacks in its config. onStart fires when the spring begins animating. onChange fires on every frame with the current value — useful for side effects that track position. onRest fires when the spring settles at its final value, signaling that the animation is complete.

In the declarative form, useSpring automatically re-runs the animation when the values passed to it change. For example, useSpring({ opacity: isVisible ? 1 : 0 }) will animate opacity every time isVisible changes. This is the simplest way to tie spring animations to component state.

In react-spring's config, what do tension and friction control?

react-spring animates with physics: tension (stiffness), friction (damping), and mass define motion. useSpring({ from, to }) returns SpringValue objects applied to animated.* components. Preset configs (gentle, wobbly, stiff, slow) cover common cases. The imperative API [springs, api] enables programmatic control via api.start(), api.stop(), and api.set(). onRest fires when animation settles.