Skip to content

react-spring-physics

  • Group: Animation
  • When it activates: Physics-based animation in React (react-spring)
  • Installed: Optional: comes with a skill bundle.

Full upstream documentation (English): SKILL.upstream.md (464 lines). Do not read it whole: use the map and read only the section you need (Read with offset/limit or Grep).

  • Use: natural, interruptible motion in React (mass/tension/friction), drag/swipe with velocity preservation, inertia and snap to grid.
  • Use: list transitions (useTransition), cascades (useTrail), reveal by viewport (useInView) or scroll (useScroll), animating react-three-fiber props with @react-spring/three.
  • Do NOT use: vanilla, Vue or Astro project without React → animejs (easing spring(...)) or gsap-scrolltrigger; timeline/scrub choreography → gsap-scrolltrigger; declarative variants with gestures → motion-framer.
Task Read only
Start a project/starter SKILL.upstream.md L26-97 (§Core Concepts) + assets/README.md (Vite react + npm i @react-spring/web)
Click / hover / trail / lists L100-176 (§1-3) or scripts/spring_generator.py --type transition
Scroll / viewport / async chains L177-236 (§4-6)
Drag with momentum / Popmotion inertia L237-259 (§7) + L290-312 + references/popmotion_api.md
Tune the feel of the spring L75-97 (presets) + scripts/physics_calculator.py --feel bouncy + references/physics_guide.md
Integrate with react-three-fiber / forms L262-330 (§Integration Patterns)
Debugging / performance L331-367 (§Performance) + L368-441 (§Common Pitfalls)
Lines Section What for
10-25 Overview When to use; packages @react-spring/web, /three, popmotion
26-97 Core Concepts Spring physics (28), useSpring patterns object vs function+api (50), config.* presets (75)
98-259 Common Patterns Click (100), trail (131), list transitions (155), scroll (177), inView (198), async chains (216), preserved velocity (237)
260-330 Integration Patterns react-three-fiber (262), Popmotion inertia (290), shake on form validation (313)
331-367 Performance Optimization precision, batched useSprings, Globals.skipAnimation
368-441 Common Pitfalls useSpring deps, mutating values, precision, velocity, mixing patterns, non-numeric strings
442-464 Resources / Related Skills Scripts, references, physics vs timeline
  • references/react_spring_api.md — hooks, animated, .to() interpolation, api.start/stop, events.
  • references/popmotion_api.md — Popmotion spring, inertia, decay, keyframes and streams.
  • references/physics_guide.md — mass/tension/friction, critical damping, tuning table.
  • scripts/spring_generator.py — click/scroll/trail/transition/inview/chain/gesture boilerplate: py -3 scripts/spring_generator.py --type gesture (Linux/mac: python3 …).
  • scripts/physics_calculator.py — computes parameters by feel or by critical damping: py -3 scripts/physics_calculator.py --feel bouncy / --critical-damping --tension 170.
  • assets/README.md — only Vite starter instructions and official links (there is no real starter_spring/ folder despite what upstream says).
  • useSpring(() => ({...}), []) with a deps array, and use api.start(); never springs.x.set() nor recreate the spring on every render.
  • Animate individual numeric values (x, rotation) and compose the transform with .to(); do not pass composite strings.
  • When interrupting an animation, pass velocity: springs.x.getVelocity() so momentum is not cut.
  • Set config.precision (e.g. 0.01) and group with useSprings/useTrail to avoid unnecessary renders.
  • Respect prefers-reduced-motion with Globals.assign({ skipAnimation: true }) (L356-367).
  • Detect the stack as described in the front-activation/skill-router skill (senzu/senzu.json → package.json). React-only library (also Next/Remix/Astro with React islands); hooks run on the client and useScroll/useInView require window, so under SSR wrap them in client-only components.
  • If the project is Vue, Svelte or vanilla, do not install it: use animejs (spring easing) or gsap-scrolltrigger; for 3D in React combine with react-three-fiber via @react-spring/three.