31.GSAP 플러그인

텍스트 애니메이션

결과가 눈에 즉시 보이는 단계다.

SplitText — 글자 분해 등장

텍스트를 chars / words / lines 단위 span으로 분해해 개별 요소에 애니메이션을 건다. revert()로 원본 DOM을 복구하는 습관이 필수다.

핵심 API

실행 결과 보기

// 1. SplitText.create()로 인스턴스 생성 (3.13+ 권장)
const split = SplitText.create(".title", {
  type: "chars,words"
});

// 2. 분해된 글자에 stagger 적용
gsap.from(split.chars, {
  opacity: 0,
  y: 40,
  duration: 0.6,
  stagger: 0.03,
  ease: "power3.out",
  onComplete: () => split.revert() // 3. 완료 후 DOM 복구
});

ScrambleText — 타이핑 해독 효과

트위닝 도중 문자가 랜덤 글자로 섞이다가 목표 텍스트로 수렴한다. chars 옵션으로 사용할 문자 셋을 지정한다.

핵심 API

실행 결과 보기

gsap.to(".code-display", {
  duration: 2,
  scrambleText: {
    text: "ACCESS GRANTED",
    chars: "01",        // 0과 1로만 섞임
    speed: 0.4,
    revealDelay: 0.5
  }
});

Text — innerHTML 순차 타이핑

innerHTML을 타이핑하듯 순서대로 채운다. delimiter로 글자 단위 vs 단어 단위를 선택한다.

핵심 API

실행 결과 보기

gsap.to(".terminal", {
  duration: 3,
  text: {
    value: "Hello, world! 타이핑 완료.",
    delimiter: "",        // 글자 단위 타이핑
    newClass: "new-char"
  },
  ease: "none"
});

SVG 드로잉 & 모핑

path 개념을 순서대로 쌓아가는 단계다. DrawSVG → MorphSVG → MotionPath 순서로 진행하면 자연스럽게 연결된다.

DrawSVG — 선 그리기 애니메이션

stroke-dashoffset 원리를 추상화해 path · circle · line을 비율(%) 또는 픽셀로 그린다.

핵심 API

실행 결과 보기

// 숨김 상태에서 시작
gsap.set(".path", { drawSVG: "0%" });

// 전체 그리기
gsap.to(".path", {
  drawSVG: "100%",
  duration: 2,
  ease: "power2.inOut"
});

// 구간 이동 애니메이션 (20%~80% → 80%~100%)
gsap.to(".path", {
  drawSVG: "80% 100%",
  duration: 1.5
});

MorphSVG — 도형 변형 트랜지션

SVG path 간 형태를 보간한다. 포인트 수가 달라도 자동 보정한다.

핵심 API

실행 결과 보기

// circle → star → heart 순환
const shapes = ["#circle", "#star", "#heart"];
let idx = 0;

function morph() {
  idx = (idx + 1) % shapes.length;
  gsap.to("#shape", {
    morphSVG: {
      shape: shapes[idx],
      type: "rotational"  // 자연스러운 회전 보간
    },
    duration: 1,
    ease: "power2.inOut",
    onComplete: morph
  });
}

morph();

MotionPath — SVG 경로 따라 이동

요소를 SVG path 위에서 이동시킨다. autoRotate로 진행 방향에 맞게 자동 회전한다.

핵심 API

실행 결과 보기

gsap.to(".rocket", {
  motionPath: {
    path: "#orbit-path",
    align: "#orbit-path",
    autoRotate: true,
    alignOrigin: [0.5, 0.5],  // 요소 중심 기준 정렬
    start: 0,
    end: 1
  },
  duration: 4,
  repeat: -1,
  ease: "none"
});

MotionPathHelper — 경로 시각 편집

브라우저에서 path를 드래그로 편집하고 좌표를 복사하는 개발 전용 도구다. 배포 전 반드시 제거한다.

핵심 API

// 개발 시에만 사용 — 배포 전 제거
import { MotionPathHelper } from "gsap/MotionPathHelper";
gsap.registerPlugin(MotionPathHelper);

MotionPathHelper.create(".rocket", {
  path: "#orbit-path",
  selected: true
});
// 편집 후 [Copy SVG] 클릭 → d 값 복사해 코드에 붙여넣기

스크롤 & 드래그 인터랙션

실제 서비스에서 가장 자주 쓰이는 패턴이다. ScrollTo → Observer → Draggable → Inertia 순서로 진행한다.

ScrollTo — 부드러운 앵커 이동

window 또는 스크롤 컨테이너를 특정 y 위치나 요소로 부드럽게 이동시킨다.

핵심 API

실행 결과 보기

// 앵커 버튼 전체에 부드러운 스크롤 적용
document.querySelectorAll("a[href^='#']").forEach(a => {
  a.addEventListener("click", e => {
    e.preventDefault();
    gsap.to(window, {
      duration: 1,
      scrollTo: {
        y: a.getAttribute("href"),
        offsetY: 80    // 고정 헤더 높이만큼 보정
      },
      ease: "power2.inOut",
      autoKill: true   // 사용자 스크롤 시 중단
    });
  });
});

Observer — 스크롤 방향 감지 UI

스크롤 · 휠 · 터치 · 포인터 방향을 통합 감지한다. 풀페이지 전환, 수평 스크롤 섹션에 활용한다.

핵심 API

실행 결과 보기

let current = 0;
const sections = gsap.utils.toArray(".section");

Observer.create({
  type: "wheel,touch",
  tolerance: 10,
  onDown: () => {
    if (current < sections.length - 1) {
      gsap.to(sections[++current], {
        yPercent: 0,
        duration: 0.9,
        ease: "power2.inOut"
      });
    }
  },
  onUp: () => {
    if (current > 0) {
      gsap.to(sections[current--], {
        yPercent: 100,
        duration: 0.9,
        ease: "power2.inOut"
      });
    }
  }
});

Draggable — 드래그 앤 드롭 카드

요소를 드래그 가능하게 만든다. bounds로 영역 제한, snap으로 격자 흡착을 구현한다.

핵심 API

실행 결과 보기

Draggable.create(".card", {
  type: "x,y",
  bounds: ".board",
  edgeResistance: 0.65,
  snap: {
    x: v => Math.round(v / 120) * 120,  // 120px 격자 흡착
    y: v => Math.round(v / 120) * 120
  },
  onDragEnd() {
    console.log("x:", this.x, "y:", this.y);
  }
});

Inertia — 드래그 관성 슬라이더

Draggable과 조합해 손을 뗐을 때 관성으로 감속하는 효과를 준다. 단독으로 gsap.to에서도 사용 가능하다.

핵심 API

실행 결과 보기

// Draggable + Inertia 조합 캐러셀
Draggable.create(".carousel-item", {
  type: "x",
  inertia: true,
  bounds: { minX: -800, maxX: 0 },
  snap: x => Math.round(x / 300) * 300  // 300px 단위 슬라이드 흡착
});

// 단독 사용 예시
gsap.to(".ball", {
  inertia: {
    x: { velocity: 1200, resistance: 300, min: 0, max: 600 }
  }
});

물리 · 레이아웃 · 고급

JS/DOM 이해도가 충분히 쌓인 뒤 도전하는 단계다. 코드 양이 적은데 결과가 극적이다.

Physics2D — 중력 파티클 효과

gravity · velocity · angle · friction으로 2D 물리 운동을 정의한다. 컨페티 이펙트 구현에 활용한다.

핵심 API

실행 결과 보기

function burst(x, y) {
  for (let i = 0; i < 30; i++) {
    const dot = document.createElement("div");
    dot.className = "dot";
    document.body.appendChild(dot);
    gsap.set(dot, { x, y });

    gsap.to(dot, {
      duration: 1.5,
      physics2D: {
        velocity: gsap.utils.random(400, 900),
        angle: gsap.utils.random(-130, -50),
        gravity: 1200,
        friction: 0.05
      },
      opacity: 0,
      onComplete: () => dot.remove()
    });
  }
}

document.addEventListener("click", e => burst(e.clientX, e.clientY));

PhysicsProps — 속도 기반 속성 애니메이션

velocity · friction으로 CSS 속성을 물리 법칙처럼 감속시킨다. 튕기는 카드, 스핀 효과에 활용한다.

핵심 API

실행 결과 보기

// 스와이프 후 카드가 날아가는 효과
card.addEventListener("pointerup", () => {
  gsap.to(card, {
    duration: 1.5,
    physicsProps: {
      x: { velocity: 600, friction: 0.15 },
      rotation: { velocity: 180, friction: 0.1 }
    },
    opacity: 0
  });
});

Flip — 레이아웃 전환 애니메이션

DOM 변경 전후의 위치 · 크기 차이를 계산해 자연스러운 레이아웃 전환을 만든다. FLIP(First, Last, Invert, Play) 패턴을 자동화한 플러그인이다.

핵심 API

실행 결과 보기

const items = document.querySelectorAll(".item");

// 1. 변경 전 상태 저장
const state = Flip.getState(items);

// 2. DOM / 클래스 변경 (그리드 ↔ 리스트 전환)
container.classList.toggle("grid-view");

// 3. 변경 전 위치에서 현재 위치로 애니메이션
Flip.from(state, {
  duration: 0.6,
  ease: "power2.inOut",
  stagger: 0.04,
  absolute: true
});

CSSRule — 전역 스타일 트위닝 (deprecated)

개별 요소가 아닌 CSS 규칙 자체를 트위닝한다. :hover 스타일이나 CSS 변수 값을 코드로 애니메이션할 때 사용했다.

핵심 API

실행 결과 보기

// ❌ deprecated — CSSRulePlugin 방식
const rule = CSSRulePlugin.getRule(".btn:hover");
gsap.to(rule, {
  duration: 1,
  cssRule: { backgroundColor: "#7F77DD" }
});

// ✅ 권장 — CSS 변수 직접 트위닝
gsap.to("html", {
  "--accent": "#534AB7",
  duration: 0.8
});

Pixi + Easel — 캔버스 렌더러 연동

PixiPlugin은 Pixi.js DisplayObject 속성을, EaselPlugin은 EaselJS 속성을 GSAP 트윈으로 제어한다.

핵심 API

import * as PIXI from "pixi.js";
PixiPlugin.registerPIXI(PIXI);   // 반드시 먼저 등록

const sprite = new PIXI.Sprite(texture);
app.stage.addChild(sprite);

gsap.to(sprite, {
  duration: 1.5,
  pixi: {
    alpha: 0.3,
    tint: 0x534AB7,
    blur: 8,
    x: 400
  },
  ease: "power2.out"
});

GSDevTools — 타임라인 디버거

타임라인에 재생 · 일시정지 · 속도 조절 UI를 붙인다. 복잡한 애니메이션 디버깅 시 필수 도구다.

핵심 API

const tl = gsap.timeline({ id: "intro" });

tl.from(".hero", { opacity: 0, y: 60, duration: 1 })
  .from(".subtitle", { opacity: 0, duration: 0.8 }, "-=0.3")
  .from(".cta", { opacity: 0, scale: 0.8 }, "-=0.2");

// 개발 시에만 추가 — 배포 전 제거
GSDevTools.create({
  animation: "intro",   // timeline id로 연결
  keyboard: true,
  minimal: false
});

npm install gsap@latest