GSAP Animation Patterns

# GSAP Animation Patterns for Google Antigravity

GSAP provides professional-grade animations with precise control. This guide covers advanced GSAP patterns optimized for Google Antigravity IDE and Gemini 3.

## Core GSAP Setup with React

```typescript
// hooks/useGsap.ts
import { useLayoutEffect, useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';

gsap.registerPlugin(ScrollTrigger);

export function useScrollAnimation<T extends HTMLElement>() {
  const containerRef = useRef<T>(null);
  const timelineRef = useRef<gsap.core.Timeline>();

  useGSAP(() => {
    if (!containerRef.current) return;

    const ctx = gsap.context(() => {
      timelineRef.current = gsap.timeline({
        scrollTrigger: {
          trigger: containerRef.current,
          start: 'top 80%',
          end: 'bottom 20%',
          toggleActions: 'play none none reverse',
          markers: process.env.NODE_ENV === 'development',
        },
      });
    }, containerRef);

    return () => ctx.revert();
  }, []);

  return { containerRef, timeline: timelineRef };
}
```

## Stagger Animation Component

```typescript
// components/AnimatedList.tsx
import { useRef } from 'react';
import { useGSAP } from '@gsap/react';
import gsap from 'gsap';

interface AnimatedListProps {
  items: Array<{ id: string; content: React.ReactNode }>;
  stagger?: number;
  duration?: number;
}

export function AnimatedList({ items, stagger = 0.1, duration = 0.6 }: AnimatedListProps) {
  const containerRef = useRef<HTMLUListElement>(null);
  const itemsRef = useRef<HTMLLIElement[]>([]);

  useGSAP(() => {
    if (!containerRef.current) return;

    gsap.context(() => {
      // Initial state
      gsap.set(itemsRef.current, {
        opacity: 0,
        y: 30,
        scale: 0.95,
      });

      // Animate in with stagger
      gsap.to(itemsRef.current, {
        opacity: 1,
        y: 0,
        scale: 1,
        duration,
        stagger: {
          each: stagger,
          ease: 'power2.out',
        },
        scrollTrigger: {
          trigger: containerRef.current,
          start: 'top 85%',
          toggleActions: 'play none none reverse',
        },
      });
    }, containerRef);
  }, [items, stagger, duration]);

  return (
    <ul ref={containerRef} className="space-y-4">
      {items.map((item, index) => (
        <li
          key={item.id}
          ref={(el) => {
            if (el) itemsRef.current[index] = el;
          }}
          className="p-4 bg-white rounded-lg shadow"
        >
          {item.content}
        </li>
      ))}
    </ul>
  );
}
```

## Complex Timeline Orchestration

```typescript
// components/HeroSection.tsx
import { useRef } from 'react';
import { useGSAP } from '@gsap/react';
import gsap from 'gsap';
import { SplitText } from 'gsap/SplitText';

gsap.registerPlugin(SplitText);

export function HeroSection() {
  const containerRef = useRef<HTMLDivElement>(null);
  const headingRef = useRef<HTMLHeadingElement>(null);
  const subtitleRef = useRef<HTMLParagraphElement>(null);
  const ctaRef = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    const ctx = gsap.context(() => {
      // Split heading into characters
      const splitHeading = new SplitText(headingRef.current, { type: 'chars,words' });
      
      // Master timeline
      const tl = gsap.timeline({
        defaults: { ease: 'power3.out' },
      });

      // Animate heading characters
      tl.from(splitHeading.chars, {
        opacity: 0,
        y: 50,
        rotateX: -90,
        stagger: 0.02,
        duration: 0.8,
      });

      // Animate subtitle
      tl.from(subtitleRef.current, {
        opacity: 0,
        y: 20,
        duration: 0.6,
      }, '-=0.4');

      // Animate CTA buttons with bounce
      tl.from(ctaRef.current?.children || [], {
        opacity: 0,
        scale: 0.8,
        y: 20,
        stagger: 0.15,
        duration: 0.5,
        ease: 'back.out(1.7)',
      }, '-=0.2');

      // Cleanup split text on unmount
      return () => splitHeading.revert();
    }, containerRef);

    return () => ctx.revert();
  }, []);

  return (
    <div ref={containerRef} className="hero-section min-h-screen flex flex-col justify-center items-center">
      <h1 ref={headingRef} className="text-6xl font-bold">
        Welcome to the Future
      </h1>
      <p ref={subtitleRef} className="text-xl mt-4 text-gray-600">
        Building amazing experiences with GSAP and React
      </p>
      <div ref={ctaRef} className="mt-8 flex gap-4">
        <button className="btn-primary">Get Started</button>
        <button className="btn-secondary">Learn More</button>
      </div>
    </div>
  );
}
```

## Scroll-Driven Parallax

```typescript
// components/ParallaxSection.tsx
export function ParallaxSection() {
  const containerRef = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    gsap.context(() => {
      gsap.to('.parallax-bg', {
        yPercent: -30,
        ease: 'none',
        scrollTrigger: {
          trigger: containerRef.current,
          start: 'top bottom',
          end: 'bottom top',
          scrub: true,
        },
      });

      gsap.to('.parallax-content', {
        yPercent: 20,
        ease: 'none',
        scrollTrigger: {
          trigger: containerRef.current,
          start: 'top bottom',
          end: 'bottom top',
          scrub: 0.5,
        },
      });
    }, containerRef);
  }, []);

  return (
    <div ref={containerRef} className="relative h-screen overflow-hidden">
      <div className="parallax-bg absolute inset-0 bg-gradient-to-b from-blue-500 to-purple-600" />
      <div className="parallax-content relative z-10 flex items-center justify-center h-full">
        <h2 className="text-4xl font-bold text-white">Parallax Magic</h2>
      </div>
    </div>
  );
}
```

## Best Practices

1. **Use Context**: Always wrap GSAP in gsap.context() for proper cleanup
2. **Prefer useGSAP**: Use the official React hook instead of useEffect
3. **Kill on Unmount**: Clean up ScrollTriggers and timelines properly
4. **Batch DOM Reads**: Use gsap.set() for initial states before animation
5. **Mobile Performance**: Use will-change sparingly, prefer transforms
6. **Accessibility**: Respect prefers-reduced-motion media query

Google Antigravity's Gemini 3 can help design complex animation sequences and automatically generate the corresponding GSAP timeline code.