Smooth Scroll Library Comparison

Best Practices & Approaches for Using GSAP with Next.js

When integrating GSAP animations into a Next.js project, it's important to consider the nature of your content and layout. Different scenarios require different approaches to ensure smooth animations and avoid common pitfalls like layout shifts and hydration issues.

Key Takeaway:

• Explore best practices for integrating GSAP animations with Next.js projects.
• Learn when to use different GSAP setup patterns for static, dynamic, and complex layouts.
• Get practical tips to avoid common pitfalls with SSR, hydration, and dynamic content.

Simple static content (no images/dynamic content)

useEffect(() => {
  const ctx = gsap.context(() => {
    // Your GSAP animations
  });
  return () => ctx.revert();
}, []);

With images/dynamic content (recommended for most cases)

useEffect(() => {
  const ctx = gsap.context(() => {
    // Your GSAP animations
  });
 
  // Refresh after images load
  const handleLoad = () => ScrollTrigger.refresh();
  window.addEventListener("load", handleLoad);
 
  return () => {
    window.removeEventListener("load", handleLoad);
    ctx.revert();
  };
}, []);

Complex layouts / Hydration issues (e.g., Next.js SSR)

useEffect(() => {
  let ctx: gsap.Context;
 
  const rafId = requestAnimationFrame(() => {
    ctx = gsap.context(() => {
      // Your GSAP animations
    });
  });
 
  return () => {
    cancelAnimationFrame(rafId);
    ctx?.revert();
  };
}, []);

Summary - When to use each approach:

Key best practices for Next.js + GSAP:

1. Always use gsap.context() - For cleanup
2. Add invalidateOnRefresh: true - Recalculates on resize/refresh
3. Call ScrollTrigger.refresh() - After dynamic content loads
4. Use requestAnimationFrame - Only when experiencing timing/layout issues
5. Check typeof window !== 'undefined' - For SSR safety (optional with "use client")

The pattern I provided is the safest/most robust for production, for simple demos you can use the basic approach.