gsap-animation

When to use

Use this skill when creating Remotion video compositions that need GSAP's advanced animation capabilities beyond Remotion's built-in interpolate() and spring().

Use GSAP when you need:

• Complex timeline orchestration (nesting, labels, position parameters like "-=0.5")
• Text splitting animation (SplitText: chars/words/lines with mask reveals)
• SVG shape morphing (MorphSVG), stroke drawing (DrawSVG), path-following (MotionPath)
• Advanced easing (CustomEase from SVG paths, RoughEase, SlowMo, CustomBounce, CustomWiggle)
• Stagger with grid, center/edges distribution
• Character scramble/decode effects (ScrambleText)
• Reusable named effects via gsap.registerEffect()

Use Remotion native interpolate() when:

• Simple single-property animations (fade, slide, scale) -- do NOT use GSAP for these
• Numeric counters/progress bars -- pure math, no timeline needed
• Standard easing curves
• Spring physics (spring())

GSAP Licensing: All plugins are 100% free since Webflow's 2024 acquisition (SplitText, MorphSVG, DrawSVG, etc.).

---

Setup

# In a Remotion project
npm install gsap

// src/gsap-setup.ts -- import once at entry point
import gsap from 'gsap';
import { SplitText } from 'gsap/SplitText';
import { MorphSVGPlugin } from 'gsap/MorphSVGPlugin';
import { DrawSVGPlugin } from 'gsap/DrawSVGPlugin';
import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
import { ScrambleTextPlugin } from 'gsap/ScrambleTextPlugin';
import { CustomEase } from 'gsap/CustomEase';
import { CustomBounce } from 'gsap/CustomBounce';
import { CustomWiggle } from 'gsap/CustomWiggle';

gsap.registerPlugin(
  SplitText, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin,
  ScrambleTextPlugin, CustomEase, CustomBounce, CustomWiggle,
);

export { gsap };

---

Core Hook: useGSAPTimeline

The bridge between GSAP and Remotion. Creates a paused timeline, seeks it to frame / fps every frame.

import { useCurrentFrame, useVideoConfig } from 'remotion';
import gsap from 'gsap';
import { useRef, useEffect } from 'react';

function useGSAPTimeline(
  buildTimeline: (tl: gsap.core.Timeline, container: HTMLDivElement) => void
) {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const containerRef = useRef<HTMLDivElement>(null);
  const tlRef = useRef<gsap.core.Timeline | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;
    const ctx = gsap.context(() => {
      const tl = gsap.timeline({ paused: true });
      buildTimeline(tl, containerRef.current!);
      tlRef.current = tl;
    }, containerRef);
    return () => { ctx.revert(); tlRef.current = null; };
  }, []);

  useEffect(() => {
    if (tlRef.current) tlRef.current.seek(frame / fps);
  }, [frame, fps]);

  return containerRef;
}