Animation Guide

Animation Implementation Guide

Library Decision

Before writing any animation, decide which library to use:

GSAP (Primary)

• ScrollTrigger for scroll-driven reveals, parallax, pinning
• SplitText for text animations (always use autoSplit: true for responsive)
• Timeline for sequenced animations (.to() chaining)
• MorphSVG for SVG path morphing
• CustomEase for branded easing curves
• Setup: always use useGSAP hook from @gsap/react

Lenis

• Smooth scroll ONLY -- never use for individual animations
• ONE instance at layout level, never per-component
• Integrate with GSAP ScrollTrigger via lenis.on('scroll', ScrollTrigger.update)
• Control: lenis.stop() for modals, lenis.start() to resume

Framer Motion

• AnimatePresence for mount/unmount animations
• layoutId for shared element transitions
• motion.div with animate, initial, exit for React state-driven animations
• Spring physics via type: "spring"
• Do NOT use for scroll animations -- use GSAP ScrollTrigger instead

Three.js / React Three Fiber

• 3D scenes only -- particles, 3D models, WebGL effects
• Use @react-three/fiber + @react-three/drei for React integration
• Always lazy-load with next/dynamic: const Scene = dynamic(() => import('./Scene'), { ssr: false })

Responsive Animation

• All animations must work at every breakpoint
• Use gsap.matchMedia() for breakpoint-specific animations
• Test with prefers-reduced-motion -- provide reduced/no-motion fallbacks

Converted and distributed by TomeVault — claim your Tome and manage your conversions.