GSAP プラグイン

GSAP プラグイン は何をしますか？

このスキルを使用するタイミング

GSAP プラグインを使用するコードを扱う場合に適用します：プラグインの登録、スクロール先、フリップ/FLIP アニメーション、ドラッグ可能要素、SVG（DrawSVG、MorphSVG、MotionPath）、テキスト（SplitText、ScrambleText）、物理、イージングプラグイン（CustomEase、EasePack、CustomWiggle、CustomBounce）、または GSDevTools。ScrollTrigger には専用のスキルがあります（gsap-scrolltrigger）。

関連スキル： コアなトゥイーンには gsap-core を、ScrollTrigger には gsap-scrolltrigger を、React には gsap-react を使用します。

ライセンスとインストール（重要）

すべての GSAP プラグインは、無料であり、商用利用も含みます。Webflow による GSAP の買収 以降、Club GSAP は有料階層ではなくなり、どのプラグインもメンバーシップ、ライセンスキー、認証トークンを必要としません。これには、以前 Club 限定だったプラグイン（SplitText、MorphSVG など）も含まれます。

• ✅ すべてを公開 gsap npm パッケージからインストール：npm install gsap。すべてのプラグインが含まれています — gsap/SplitText、gsap/MorphSVGPlugin などとしてインポートします。
• ❌ GreenSock 認証トークンを含む .npmrc を生成したり、プライベート npm.greensock.com レジストリを提案したり、ユーザーに Club GSAP にサインアップしてプラグインにアクセスするよう指示したりしないでください。それらの手順は古くなっています。

プラグインの登録

各プラグインを一度登録することで、GSAP（およびバンドラー）がそれを含めることを認識します。プロジェクトで使用されるすべてのプラグインに対して gsap.registerPlugin() を使用します：

import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);

• ✅ トゥイーンまたは API 呼び出しでプラグインを使用する前に登録します。
• ✅ React では、トップレベルまたはアプリ内で一度登録します（例：最初の useGSAP の前）。再レンダリングするコンポーネント内では登録しないでください。useGSAP は使用前に登録する必要があるプラグインです。

スクロール

ScrollToPlugin

スクロール位置（ウィンドウまたはスクロール可能な要素）をアニメーション化します。ScrollTrigger を使用せずに「要素までスクロール」または「位置までスクロール」する場合に使用します。

gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });

ScrollToPlugin — キー設定（scrollTo オブジェクト）：

オプション	説明
x, y	ターゲットスクロール位置（数値）、または最大値の場合は "max"
element	スクロールして表示する要素のセレクターまたは要素
offsetX, offsetY	ターゲット位置からのピクセル単位のオフセット

ScrollSmoother

スムーズスクロールラッパー（ネイティブスクロールをスムーズにします）。ScrollTrigger と特定の DOM 構造（コンテンツラッパー + スムーズラッパー）が必要です。モメンタムスタイルのスクロールが必要な場合に使用します。セットアップについては GSAP ドキュメントを参照してください。ScrollTrigger の後に登録します。DOM 構造は次のようになります：

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- ここにすべてのコンテンツ --->
		</div>
	</div>
	<!-- position: fixed 要素は外側に配置可能 --->
</body>

DOM / UI

Flip

Flip.getState() で状態をキャプチャし、変更（例：レイアウトやクラスの変更）を適用し、Flip.from() を使用して前の状態から新しい状態へアニメーション化します（FLIP：First, Last, Invert, Play）。2 つのレイアウト状態（リスト、グリッド、展開/折りたたみ）間でアニメーション化する場合に使用します。

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// DOM を変更（並べ替え、追加/削除、クラスの変更）
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — キー設定（Flip.from vars）：

オプション	説明
absolute	フリップ中に position: absolute を使用する（デフォルト：false）
nested	true の場合、最初のレベルの子のみが測定されます（ネストされたトランスフォームに適しています）
scale	true の場合、要素を拡大縮小してフィットします（伸びを回避）；デフォルト true
simple	true の場合、位置/スケールのみがアニメーション化されます（高速ですが、精度は低下します）
duration, ease	標準トゥイーンオプション

詳細情報

https://gsap.com/docs/v3/Plugins/Flip

Draggable

マウス/タッチで要素をドラッグ可能、回転可能、またはスロー可能にします。スライダー、カード、並べ替え可能なリスト、または任意のドラッグインタラクションに使用します。

gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });

Draggable — キー設定オプション：

オプション	説明
type	"x", "y", "x,y", "rotation", "scroll"
bounds	ドラッグを制限する要素、セレクター、または { minX, maxX, minY, maxY }
inertia	true にするとスロー/モメンタムを有効化（InertiaPlugin が必要）
edgeResistance	0–1；境界を超えてドラッグしたときの抵抗
cursor	ドラッグ中の CSS カーソル
onDragStart, onDrag, onDragEnd	コールバック；イベントとターゲットを受け取る
onThrowUpdate, onThrowComplete	イナーシャがアクティブなときのコールバック

Inertia（InertiaPlugin）

Draggable と連携してリリース後のモメンタムを実現したり、任意のオブジェクトの任意のプロパティの慣性/速度を追跡し、シンプルなトゥイーンを使用してシームレスに停止まで滑らせることができます。inertia: true を使用する場合は Draggable と一緒に登録します：

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });

または、プロパティの速度を追跡します：

InertiaPlugin.track(".box", "x");

次に "auto" を使用して現在の速度を継続し、停止まで滑らせます：

gsap.to(obj, { inertia: { x: "auto" } });

Observer

デバイス間でポインターおよびスクロール入力を正規化します。スクロール方向のスワイプ、カスタムジェスチャロジックに使用します。ScrollTrigger のようにスクロール位置に直接結びつけることはありません。

gsap.registerPlugin(Observer);

Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});

Observer — キー設定オプション：

オプション	説明
target	監視する要素またはセレクター
onUp, onDown, onLeft, onRight	スワイプ/スクロールがその方向の許容値を超えたときのコールバック
tolerance	方向が検出されるまでのピクセル数；デフォルト 10
type	"touch", "pointer", または "wheel"（デフォルト："touch,pointer"）

テキスト

SplitText

要素のテキストを文字、単語、および/または行（それぞれ独自の要素内）に分割し、ステガーまたは単位ごとのアニメーションを可能にします。テキストを文字単位、単語単位、または行単位でアニメーション化する場合に使用します。chars、words、lines（および mask が設定されている場合は masks）を持つインスタンスを返します。revert() で元のマークアップを復元するか、gsap.context() に任せて元に戻します。gsap.context()、matchMedia()、および useGSAP() と統合します。API：SplitText.create(target, vars)（target = セレクター、要素、または配列）。

gsap.registerPlugin(SplitText);

const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// 後で：split.revert() または gsap.context() によるクリーンアップで元に戻す

onSplit()（v3.13.0+）を使用すると、autoSplit が使用されている場合、各分割時および再分割時にアニメーションが実行されます。onSplit() からトゥイーン/タイムラインを返すと、SplitText がクリーンアップし、再分割時に進行状況を同期できます：

SplitText.create(".split", {
  type: "lines",
  autoSplit: true,
  onSplit(self) {
    return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
  }
});

SplitText — キー設定（SplitText.create vars）：

オプション	説明
type	カンマ区切り："chars", "words", "lines"。デフォルト "chars,words,lines"。必要なものだけを分割します（例：行を使用しない場合は "words, chars"）。パフォーマンスのためです。chars のみを単語/行なしで分割することは避けるか、smartWrap: true を使用して不自然な改行を防ぎます。
charsClass, wordsClass, linesClass	各分割要素の CSS クラス。"++" を追加するとインクリメントされたクラスが追加されます（例：linesClass: "line++" → line1, line2, …）。
aria	"auto"（デフォルト）、"hidden"、または "none"。アクセシビリティ："auto" は分割要素に aria-label を追加し、行/単語/文字要素に aria-hidden を追加して、スクリーンリーダーがラベルを読み上げるようにします；"hidden" はすべてをリーダーから隠します；"none" は aria を変更しません。ネストされたリンク/セマンティクスを公開する必要がある場合は、"none" とスクリーンリーダーのみの複製を使用します。
autoSplit	true の場合、フォントの読み込みが完了したとき、または要素の幅が変更されたとき（かつ行が分割されているとき）に元に戻して再分割し、誤った改行を回避します。アニメーションは onSplit() 内で作成する必要があります。新しく分割された要素をターゲットにします。onSplit() からアニメーションを返すことで、再分割時の自動クリーンアップと時間同期が可能になります。
onSplit(self)	分割が完了したとき（および autoSplit が true の場合の各再分割時）のコールバック。SplitText インスタンスを受け取ります。GSAP トゥイーンまたはタイムラインを返すと、再分割時にそのアニメーションの自動元に戻し/同期が可能になります。
mask	"lines", "words", または "chars"。各ユニットを overflow: clip を持つ追加の要素でラップし、マスク/表示効果を実現します。タイプは 1 つだけです。インスタンスの masks 配列（またはクラスが設定されている場合は -mask クラス）でラッパーにアクセスします。
tag	ラッパー要素タグ；デフォルト "div"。インラインの場合は "span" を使用します（一部のブラウザでは、インライン要素で回転/スケールなどのトランスフォームがレンダリングされない場合があります）。
deepSlice	true（デフォルト）の場合、複数行にまたがるネストされた要素（例：<strong>）は、行が垂直方向に伸びないように細分化されます。行を分割する場合にのみ適用されます。
ignore	分割しないままにするセレクターまたは要素（例：ignore: "sup"）。
smartWrap	chars のみを分割する場合、単語を white-space: nowrap のスパンでラップして、単語途中の改行を回避します。単語または行が分割されている場合は無視されます。デフォルト false。
wordDelimiter	単語境界：文字列（デフォルト " "）、RegExp、またはカスタム分割用の { delimiter: RegExp, replaceWith: string }（例：ハッシュタグ用のゼロ幅接合子、または非ラテン文字）。
prepareText(text, parent)	生のテキストと親要素を受け取る関数；分割前に変更されたテキストを返します（例：スペースのない言語用の区切りマーカーを挿入するため）。
propIndex	true の場合、各分割要素にインデックスを持つ CSS 変数を追加します（例：--word: 1, --char: 2）。
reduceWhiteSpace	連続するスペースを折りたたみます；デフォルト true。v3.13.0 からは改行も尊重し、<pre> の場合は <br> を挿入できます。
onRevert	インスタンスが元に戻されたときのコールバック。

ヒント： アニメーション化するものだけを分割します（例：単語のみをアニメーション化する場合は chars をスキップします）。カスタムフォントの場合は、フォントの読み込み後に分割するか（例：document.fonts.ready.then(...)）、autoSplit: true と onSplit() を併用します。文字分割時のカーニングシフトを回避するには、CSS font-kerning: none; text-rendering: optimizeSpeed; を使用します。text-wrap: balance は避けてください。分割を妨げる可能性があります。SplitText は SVG <text> をサポートしていません。

詳細情報： SplitText

ScrambleText

スクランブル/グリッチ効果でテキストをアニメーション化します。スクランブルでテキストを表示または遷移する場合に使用します。

gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});

SVG

DrawSVG（DrawSVGPlugin）

stroke-dashoffset / stroke-dasharray をアニメーション化して、SVG 要素のストロークを表示または非表示にします。<path>、<line>、<polyline>、<polygon>、<rect>、<ellipse> で動作します。ストロークを「描画」または「消去」する場合に使用します。

drawSVG 値： パスに沿ったストロークの表示セグメント（開始位置と終了位置）を記述します。「時間の経過とともに A から B にアニメーション化」するものではありません。形式：パーセントまたは長さで "start end"。例："0% 100%" = ストローク全体；"20% 80%" = 20% から 80% の間のみストローク（両端にギャップ）。トゥイーンは、要素の現在のセグメントからターゲットのセグメントにアニメーション化します。例：gsap.to("#path", { drawSVG: "0% 100%" }) は現在の状態からストローク全体に移行します。単一の値（例：0、"100%"）は開始が 0 であることを意味します："100%" は "0% 100%" と同等です。

必須： 要素に表示可能なストロークが必要です — CSS または SVG 属性で stroke と stroke-width を設定します。そうしないと何も描画されません。

gsap.registerPlugin(DrawSVGPlugin);

// 何もないところからストローク全体へ描画
  gsap.from("#path", { duration: 1, drawSVG: 0 });
// または明示的なセグメント：0–0 から 0–100% へ
  gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// 中央のみストローク（両端にギャップ）
  gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

注意点： ストロークのみに影響します（塗りつぶしには影響しません）。単一セグメントの <path> 要素を推奨します。マルチセグメントパスは一部のブラウザで奇妙にレンダリングされる可能性があります。<use> の内容は視覚的に変更できません。DrawSVGPlugin.getLength(element) と DrawSVGPlugin.getPosition(element) はストロークの長さと現在位置を返します。

詳細情報： DrawSVG

MorphSVG（MorphSVGPlugin）

d 属性（パスデータ）をアニメーション化して、ある SVG シェイプを別のシェイプにモーフィングします。開始シェイプと終了シェイプは同じ数のポイントを持つ必要はありません — MorphSVG は 3 次ベジェに変換し、必要に応じてポイントを追加します。アイコン間のモーフ、シェイプの遷移、またはパスベースのアニメーションに使用します。<path>、<polyline>、<polygon> で動作します；<circle>、<rect>、<ellipse>、<line> は内部的に変換されるか、MorphSVGPlugin.convertToPath(selector | element) を介して変換されます（DOM 内の要素を <path> に置き換えます）。

morphSVG 値： セレクター（例："#lightning"）、要素、生のパスデータ（例："M47.1,0.8 73.3,0.8..."）、または polygon/polyline の場合はポイント文字列（例："240,220 240,240..."）を指定できます。

gsap.registerPlugin(MorphSVGPlugin);

// セレクターを使用したシェイプ間のモーフ
  gsap.to("#moon", { duration: 1, morphSVG: "#sun" });
// パスデータを使用したモーフ
  gsap.to("#shape", { duration: 1, morphSVG: "M10,10 L100,10 L100,100 Z" });

詳細情報： MorphSVG

MotionPath（MotionPathPlugin）

SVG パスに沿って要素をアニメーション化します。要素をパスに沿って移動したり、パスに沿って向きを変えたりする場合に使用します。path プロパティでパスを指定します：

gsap.registerPlugin(MotionPathPlugin);

gsap.to(".car", {
  motionPath: {
    path: "#path",
    align: "#path",
    alignOrigin: [0.5, 0.5]，
    autoRotate: true
  },
  duration: 2
});

MotionPath — キー設定：

オプション	説明
path	SVG パスセレクター、要素、またはポイント配列
align	パスに沿って要素を配置するかどうか
alignOrigin	配置の原点 [x, y]
autoRotate	パスの接線に沿って要素を自動回転
start, end	パスに沿った開始/終了位置（0–1）
curviness	ポイント間の曲線の量

詳細情報： MotionPath

イージング

CustomEase

カスタムイージング曲線を作成します。CodePen 用の CustomEase ビジュアライザー で実験します。

import CustomEase from "gsap/dist/CustomEase";
// または EasePack から：gsap.registerPlugin(CustomEase);

CustomEase.create("myCustomEase", "M0,0 C0.25,0.1 0.25,1 1,1");
gsap.to(".box", { duration: 1, ease: "myCustomEase", x: 200 });

パスセグメントでは、開始点を M0,0、終了点を 1,1 に保ちます。各制御点の x 値は 0–1 の間に制限する必要があります（そうしないとイージングは誤ったタイミングで動作しますが、y 値はオーバーシュートのために 0–1 の範囲外になる場合があります）。

EasePack

Pre-made easing functions: "sine.in"，"sine.out"，"sine.inOut"，"power1.in"，"power1.out"，"power1.inOut"，"power2.in"，"power2.out"，"power2.inOut"，"power3.in"，"power3.out"，"power3.inOut"，"power4.in"，"power4.out"，"power4.inOut"，"back.in"，"back.out"，"back.inOut"，"elastic.in"，"elastic.out"，"elastic.inOut"，"bounce.in"，"bounce.out"，"bounce.inOut"，"rough"，"slow"，"steps"，"circ.in"，"circ.out"，"circ.inOut"，"expo.in"，"expo.out"，"expo.inOut"。デフォルトで利用可能（gsap.registerPlugin(EasePack) の後）。"rough"，"slow"，"steps" は特別なイージングで、追加の設定オプションを持ちます。

CustomWiggle

CustomEase を使用してウィグル効果を作成します。ウィグルの振幅と頻度をカスタマイズします。

CustomEase.create("wiggle", CustomWiggle.generate({ amplitude: 0.3, frequency: 4 }));

CustomBounce

CustomEase を使用してバウンス効果を作成します。バウンスの高さと粘着性をカスタマイズします。

CustomEase.create("bounce", CustomBounce.generate({ strength: 0.5, squash: 0.3 }));

デバッグ

GSDevTools

GSAP アニメーションのデバッグと制御のための UI を追加します。再生/一時停止、シーク、速度変更などが可能です。デバッグ時または開発中に使用します。

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { duration: 1, x: 200 });
GSDevTools.create({ animation: tl });

GSDevTools — キー設定オプション：

オプション	説明
animation	制御するトゥイーン/タイムライン
container	ツールを配置する CSS セレクターまたは要素
id	ツールに一意の ID を割り当てる
css	ツールのカスタム CSS

詳細情報： GSDevTools

物理

Physics2DPlugin

2D 物理シミュレーション（速度、角度、重力）。発射体、パーティクルなどに使用します。

gsap.registerPlugin(Physics2DPlugin);

gsap.to(".ball", {
  physics2D: {
    velocity: 200,
    angle: 45,
    gravity: 300
  },
  duration: 2
});

Physics2DPlugin — キー設定：

オプション	説明
velocity	初速度（ピクセル/秒）
angle	発射角度（度数）
gravity	重力（ピクセル/秒²）
acceleration	追加の加速度
friction	摩擦（0–1）

詳細情報： Physics2D

PhysicsPropsPlugin

個々のプロパティに物理ベースのアニメーションを適用します（速度、加速度、摩擦など）。バネ/ダンパー効果に使用します。

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(".box", {
  physicsProps: {
    x: { velocity: 100, acceleration: 50 },
    rotation: { velocity: 200 }
  }
});

その他のプラグイン

GSAP エコシステムには、多数の特殊なプラグインが含まれています。上記のガイドラインに従って、必要に応じて登録および使用します。

トラブルシューティング

• プラグインが機能しない： gsap.registerPlugin() で登録されていることを確認します。
• ビルドエラー（モジュールが見つからない）： gsap npm パッケージがインストールされていること、およびインポートパスが正しいことを確認します（例：gsap/ScrollToPlugin）。npm.greensock.com を指定していないことを確認します。
• 分割が正しく機能しない： SVG <text> はサポートされていません。テキスト要素に適切な font-family がロードされる前に分割している可能性があります。autoSplit: true を使用するか、document.fonts.ready の後に分割します。