GSAP
コアトゥイーンメソッド
- gsap.to(targets, vars) — 現在の状態から
varsへアニメーション。最も一般的。 - gsap.from(targets, vars) —
varsから現在の状態へアニメーション（登場時）。 - gsap.fromTo(targets, fromVars, toVars) — 明示的な開始と終了を指定。
- gsap.set(targets, vars) — 即座に適用（duration 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 — repeat と併用して方向を反転。 - onComplete、onStart、onUpdate — コールバック。
- immediateRender — from()/fromTo() ではデフォルト
true。同じプロパティと要素を後からトゥイーンする場合はfalseに設定して上書きを防ぎます。
トランスフォームとCSS
生の transform 文字列よりも GSAP の トランスフォームエイリアス を推奨:
| GSAP プロパティ | 同等 |
|---|---|
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と併用しないでください。 - Directional rotation —
"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 });
位置パラメータ
3番目の引数で配置を制御:
- 絶対:
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 — すべての子トゥイーンにマージされる変数。
タイムラインのネスト
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()。
パフォーマンス
Transform と Opacity を優先
x、y、scale、rotation、opacity のアニメーションはコンポジター上で処理されます。transform で同じ効果が得られる場合は、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 を使用してください。
クリーンアップ
画面外のアニメーションは一時停止または破棄してください。
参考資料（オンデマンドで読み込み）
- references/effects.md — ドロップインエフェクト: タイプライターテキスト、オーディオビジュアライザー。HyperFrames で既製のエフェクトパターンが必要な場合に参照してください。
ベストプラクティス
- camelCase のプロパティ名を使用し、トランスフォームエイリアスと autoAlpha を優先。
- delay によるチェーンよりもタイムラインを優先し、位置パラメータを使用。
- 読みやすいシーケンスのために
addLabel()でラベルを追加。 - タイムラインコンストラクタに defaults を渡す。
- 再生制御が必要な場合は、トゥイーン/タイムラインの戻り値を変数に格納。
禁止事項
- transform で十分な場合にレイアウトプロパティ（width/height/top/left）をアニメーションしない。
- 同じ SVG 要素で svgOrigin と transformOrigin の両方を使用しない。
- タイムラインでシーケンス処理できる場合に delay でアニメーションをチェーンしない。
- DOM が存在する前にトゥイーンを作成しない。
- クリーンアップを省略しない — 不要になったトゥイーンは必ず破棄する。