GSAP
코어 트윈 메서드
- gsap.to(targets, vars) — 현재 상태에서
vars로 애니메이션. 가장 일반적입니다. - gsap.from(targets, vars) —
vars에서 현재 상태로 애니메이션 (등장). - gsap.fromTo(targets, fromVars, toVars) — 명시적인 시작 및 끝.
- gsap.set(targets, vars) — 즉시 적용 (지속 시간 0).
항상 camelCase 속성 이름을 사용하세요 (예: backgroundColor, rotationX).
공통 vars
- duration — 초 (기본값 0.5).
- delay — 시작 전 지연 시간(초).
- ease —
"power1.out"(기본값),"power3.inOut","back.out(1.7)","elastic.out(1, 0.3)","none". - stagger — 숫자
0.1또는 객체:{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(기본값),true, 또는"auto". - repeat — 숫자 또는 무한 반복은
-1. yoyo — 반복 시 방향을 번갈아 가며 진행. - onComplete, onStart, onUpdate — 콜백.
- immediateRender — from()/fromTo()의 기본값은
true. 나중에 같은 속성+요소를 대상으로 하는 트윈에서 덮어쓰기를 방지하려면false로 설정하세요.
변환 및 CSS
원시 transform 문자열보다 GSAP의 변환 별칭을 선호하세요:
| GSAP 속성 | 동등한 CSS |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y (%) |
scale, scaleX, scaleY | scale |
rotation | rotate (deg) |
rotationX, rotationY | 3D rotate |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha —
opacity보다 선호하세요. 0일 경우:visibility: hidden도 설정합니다. - CSS 변수 —
"--hue": 180. - svgOrigin (SVG 전용) — 전역 SVG 좌표 공간 원점.
transformOrigin과 함께 사용하지 마세요. - 방향 회전 —
"360_cw","-170_short","90_ccw". - clearProps —
"all"또는 쉼표로 구분; 완료 시 인라인 스타일을 제거합니다. - 상대 값 —
"+=20","-=10","*=2".
함수 기반 값
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
이징
내장 이징: power1–power4, back, bounce, circ, elastic, expo, sine. 각각 .in, .out, .inOut이 있습니다.
기본값
gsap.defaults({ duration: 0.6, ease: "power2.out" });
트윈 제어
const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);
gsap.matchMedia() (반응형 + 접근성)
미디어 쿼리가 일치할 때만 설정을 실행하고, 일치하지 않으면 자동으로 되돌립니다.
let mm = gsap.matchMedia();
mm.add(
{
isDesktop: "(min-width: 800px)",
reduceMotion: "(prefers-reduced-motion: reduce)",
},
(context) => {
const { isDesktop, reduceMotion } = context.conditions;
gsap.to(".box", {
rotation: isDesktop ? 360 : 180,
duration: reduceMotion ? 0 : 2,
});
},
);
타임라인
타임라인 생성
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
위치 매개변수
세 번째 인수가 배치를 제어합니다:
- 절대:
1— 1초 지점 - 상대:
"+=0.5"— 끝난 후;"-=0.2"— 끝나기 전 - 레이블:
"intro","intro+=0.3" - 정렬:
"<"— 이전과 같은 시작;">"— 이전이 끝난 후;"<0.2"— 이전 시작 후 0.2초
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // .a와 같은 시작
tl.to(".c", { opacity: 0 }, "<0.2"); // .b 시작 후 0.2초
레이블
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
타임라인 옵션
- paused: true — 일시 중지된 상태로 생성;
.play()를 호출하여 시작합니다. - repeat, yoyo — 전체 타임라인에 적용됩니다.
- defaults — 모든 하위 트윈에 병합되는 vars입니다.
타임라인 중첩
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
재생 제어
tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().
성능
변환과 불투명도 선호
x, y, scale, rotation, opacity 애니메이션은 컴포지터에서 처리됩니다. 변환으로 동일한 효과를 얻을 수 있다면 width, height, top, left를 피하세요.
will-change
will-change: transform;
실제로 애니메이션되는 요소에만 사용하세요.
잦은 업데이트를 위한 gsap.quickTo()
let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
xTo(e.pageX);
yTo(e.pageY);
});
여러 트윈보다 스태거
수동 지연이 있는 개별 트윈 대신 stagger를 사용하세요.
정리
화면 밖 애니메이션은 일시 중지하거나 종료(kill)하세요.
참조 (필요 시 로드)
- references/effects.md — 바로 사용 가능한 효과: 타자기 텍스트, 오디오 시각화 도우미. HyperFrames용 기성 효과 패턴이 필요할 때 읽으세요.
모범 사례
- camelCase 속성 이름을 사용하고, 변환 별칭과 autoAlpha를 선호하세요.
- 지연(delay) 체이닝보다 타임라인을 선호하고 위치 매개변수를 사용하세요.
- 읽기 쉬운 시퀀싱을 위해
addLabel()로 레이블을 추가하세요. - 타임라인 생성자에 defaults를 전달하세요.
- 재생 제어가 필요할 때 트윈/타임라인의 반환 값을 저장하세요.
하지 말아야 할 것
- 변환으로 충분할 때 레이아웃 속성(width/height/top/left)을 애니메이션하지 마세요.
- 같은 SVG 요소에 svgOrigin과 transformOrigin을 동시에 사용하지 마세요.
- 타임라인이 시퀀싱할 수 있을 때 delay로 애니메이션을 체이닝하지 마세요.
- DOM이 존재하기 전에 트윈을 생성하지 마세요.
- 정리를 건너뛰지 마세요 — 더 이상 필요하지 않으면 항상 트윈을 종료(kill)하세요.