Skip to main content
Version: next

withSpring

withSpring animates using spring physics rather than a fixed duration. It's the default for most UI motion (buttons, cards, modals) since it feels responsive rather than mechanical.

Signature​

function withSpring(
  to: number | string | object | array,
  options?: {
    stiffness?: number;
    damping?: number;
    mass?: number;
    onStart?: () => void;
    onChange?: (value: number) => void;
    onComplete?: () => void;
  }
): Descriptor;

Defaults: stiffness 170, damping 14, mass 1.

tip

Need an exact duration instead of physics? Use withTiming. Reach for withSpring when motion should feel responsive and natural.

Usage​

import { useValue, withSpring, animate } from 'react-ui-animate';

function Expandable() {
  const [width, setWidth] = useValue(100);

  return (
    /* Spring feels responsive — physics instead of a fixed duration */
    <animate.div
      style={{ width, height: 100, background: '#60a5fa' }}
      onClick={() => setWidth(withSpring(200))}
    />
  );
}
Preview

Tuning stiffness/damping/mass​

  • stiffness: speed and bounce. Low (50–100): slow, gentle. High (300+): fast, snappy.
  • damping: how much overshoot. Low (5–15): very bouncy. High (30+): minimal bounce, controlled.
  • mass: inertia. Low (0.5–1, default): quick to respond. High (3+): heavy, slow to start/stop.

Objects and arrays​

withSpring animates every key of an object/array useValue with the same driver in one call:

const [position, setPosition] = useValue({ x: 0, y: 0 });
/* One call springs every key together */
setPosition(withSpring({ x: 100, y: 100 }));
Preview

Next steps​