gsap-plugins

GSAP プラグイン

このスキルを使う場面

GSAP プラグインを使用するコードを作成またはレビューするときに適用します。プラグインの登録、スクロール移動、Flip／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 GSAP 限定だったプラグイン（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>
	
</body>

DOM／UI

Flip

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

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// change DOM (reorder, add/remove, change classes)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — 主な設定（Flip.from の変数）：

オプション	説明
absolute	Flip 中に 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 });
// later: split.revert() or let gsap.context() cleanup revert

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"）。単語や行を分割せずに文字だけを分割するのは避けるか、予期しない位置での改行を防ぐために 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() からアニメーションを return してください。
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 の span で囲み、単語の途中で改行されないようにします。単語または行を分割する場合は無視されます。デフォルトは 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	インスタンスが元に戻されたときのコールバックです。

ヒント： アニメーションさせる要素だけを分割してください（例：単語だけをアニメーションさせる場合は文字の分割を省略します）。カスタムフォントを使用する場合は、フォントの読み込み後に分割する（例：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);

// draw from nothing to full stroke
gsap.from("#path", { duration: 1, drawSVG: 0 });
// or explicit segment: from 0–0 to 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// stroke only in the middle (gaps at ends)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

注意事項： ストロークにのみ作用します（塗りには作用しません）。単一セグメントの <path> 要素を推奨します。複数セグメントのパスは、一部のブラウザーで正しく描画されない場合があります。<use> の内容は視覚的に変更できません。DrawSVGPlugin.getLength(element) と DrawSVGPlugin.getPosition(element) は、ストロークの長さと現在の位置を返します。

詳細はこちら： DrawSVG

MorphSVG (MorphSVGPlugin)

d 属性（パスデータ）をアニメーションさせて、ある SVG シェイプを別のシェイプにモーフィングします。開始シェイプと終了シェイプのポイント数が同じである必要はありません。MorphSVG はキュービックベジェに変換し、必要に応じてポイントを追加します。アイコン同士のモーフィング、シェイプの変化、パスベースのアニメーションに使用します。<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 の場合は points 文字列（例："240,220 240,70 70,70 70,220"）を指定できます。設定全体を指定するには、shape のみを必須プロパティとする オブジェクト形式を使用します。

gsap.registerPlugin(MorphSVGPlugin);

// convert primitives to path first if needed:
MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");

gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
// object form:
gsap.to("#diamond", {
  duration: 1,
  morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
});

MorphSVG — 主な設定（morphSVG オブジェクト）：

オプション	説明
shape	(必須。) 対象シェイプ：セレクター、要素、または生のパス文字列。
type	"linear"（デフォルト）または "rotational"。rotational は角度と長さを補間するため、モーフィング中の折れを避けられる場合があります。linear で見た目が不自然な場合に試してください。
map	セグメントの対応付け方法："size"（デフォルト）、"position"、または "complexity"。開始側と終了側のセグメントが揃わない場合に使用します。どれも適さない場合は、複数のパスに分割してそれぞれをモーフィングしてください。
shapeIndex	開始パスのどのポイントを終了パスの最初のポイントに対応させるかを指定します（シェイプが「交差」したり反転したりするのを防ぎます）。単一セグメントのパスでは数値、複数セグメントでは 配列（例：[5, 1, -8]）を指定します。負の値はそのセグメントを逆方向にします。shapeIndex: "log" を一度指定して自動計算された値をログに出力し、その数値／配列を tween に貼り付けます。findShapeIndex(start, end)（独立したユーティリティ）を使うと、適切な値を見つけるためのインタラクティブな UI を利用できます。閉じたパスにのみ適用されます。
smooth	（v3.14 以降）。スムージング用のポイントを追加します。数値（例：80）、"auto"、またはオブジェクト：{ points: 40 | "auto", redraw: true | false, persist: true | false }。redraw: false は元のアンカーを保持します（完全な忠実度を保ち、間隔は不均一になります）。persist: false は tween 終了時に追加したポイントを削除します。デフォルトのモーフィングがギザギザしたり不自然に見えたりする場合に使用してください。
curveMode	ブール値（v3.14 以降）。カーブ上の折れを避けるため、生の x/y 座標ではなく制御ハンドルの角度／長さを補間します。モーフィングの途中で折れが生じる場合に試してください。
origin	type: "rotational" の回転原点。文字列："50% 50%"（デフォルト）、または開始時と終了時で異なる原点を指定する場合は "20% 60%, 35% 90%"。
precision	出力パスデータの小数点以下の桁数。デフォルトは 2 です。
precompile	事前計算済みのパス文字列の配列（または precompile: "log" を一度指定して、コンソールの内容をコピーします）。時間のかかる起動時の計算を省略できます。非常に複雑なモーフィングに使用してください。<path> のみ対応します（polygon/polyline は事前に変換してください）。
render	更新ごとに呼び出される関数（rawPath, target）です。例：キャンバスに描画します。RawPath はセグメントの配列です（各セグメントは、x,y のキュービックベジェ座標が交互に並ぶ配列です）。
updateTarget	render を使用する場合（例：キャンバスのみで描画する場合）、updateTarget: false を設定すると元の <path> は更新されません。MorphSVGPlugin.defaultUpdateTarget でデフォルト値を設定できます。

ユーティリティ： MorphSVGPlugin.convertToPath(selector | element) は、circle/rect/ellipse/line/polygon/polyline を DOM 内で <path> に変換します。MorphSVGPlugin.rawPathToString(rawPath) と stringToRawPath(d) は、パス文字列と raw 配列を相互に変換します。プラグインは対象の元の d を保存します（例：元に戻す tween では morphSVG: "#originalId" または同じ要素を指定します）。

ヒント： ねじれたり反転したりするモーフィングでは、shapeIndex を設定します（"log" または findShapeIndex() を使用します）。複数セグメントのパスでは、shapeIndex は配列（セグメントごとに 1 つの値）です。最初のフレームの表示が遅い場合にのみ precompile を使用してください。tween 中のカクつきは解消しません（必要に応じて SVG を簡略化するか、サイズを小さくしてください）。

詳細： MorphSVG

MotionPath（MotionPathPlugin）

SVG パスに沿って要素をアニメーションさせます。オブジェクトをパス（曲線やカスタムルートなど）に沿って移動させる場合に使用します。

gsap.registerPlugin(MotionPathPlugin);

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

MotionPath — 主な設定（motionPath オブジェクト）：

オプション	説明
path	SVG パス要素、セレクター、またはパスデータ文字列
align	対象を位置合わせするパス要素またはセレクター
alignOrigin	[x, y] の原点（0～1）。デフォルトは [0.5, 0.5]
autoRotate	パスの接線に沿うよう要素を回転させます
curviness	0～2。パスのスムージング

MotionPathHelper

MotionPath 用のビジュアルエディター（位置合わせ、オフセット）。開発中にパスの位置合わせを調整するために使用します。

gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);

const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
// adjust in UI, then use helper.path or helper.getProgress() in your animation

イージング

CustomEase

カスタムイージングカーブ（cubic-bezier または SVG パス）を使用できます。組み込みのイージングでは不十分な場合に使用します。基本的な使い方は gsap-core で説明しています。使用する際は登録してください。

gsap.registerPlugin(CustomEase);
const ease = CustomEase.create("name", ".17,.67,.83,.67");
gsap.to(".el", { x: 100, ease: ease, duration: 1 });

EasePack

名前付きイージングを追加します（SlowMo、RoughEase、ExpoScaleEase など）。トゥイーンでイージング名を登録して使用します。

CustomWiggle

揺れや震えのイージングです。値を複数回振動させたい場合に使用します。

CustomBounce

強さを設定できるバウンススタイルのイージングです。

物理演算

Physics2D（Physics2DPlugin）

2D 物理演算（速度、角度、重力）を扱います。簡単な物理演算（飛翔体やバウンドなど）を使ってアニメーションさせる場合に使用します。

gsap.registerPlugin(Physics2DPlugin);

gsap.to(".ball", {
  duration: 2,
  physics2D: {
    velocity: 250,
    angle: 80,
    gravity: 500
  }
});

PhysicsProps（PhysicsPropsPlugin）

プロパティ値に物理演算を適用します。物理演算に基づくプロパティアニメーションに使用します。

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(".obj", {
  duration: 2,
  physicsProps: {
    x: { velocity: 100, end: 300 },
    y: { velocity: -50, acceleration: 200 }
  }
});

開発

GSDevTools

タイムラインのスクラブ、アニメーションの切り替え、デバッグを行うための UI です。開発中のみ使用し、製品には含めないでください。タイムライン参照を使って登録し、インスタンスを作成します。

gsap.registerPlugin(GSDevTools);
GSDevTools.create({ animation: tl });

その他

Pixi（PixiPlugin）

GSAP と PixiJS を連携し、Pixi の表示オブジェクトをアニメーションさせます。GSAP で Pixi オブジェクトをアニメーションさせる場合に登録してください。

gsap.registerPlugin(PixiPlugin);

const sprite = new PIXI.Sprite(texture);
gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });

ベストプラクティス

• ✅ 使用するすべてのプラグインは、初めて使用する前に gsap.registerPlugin() で登録してください。
• ✅ レイアウト遷移には Flip.getState() → DOM の変更 → Flip.from() を使用してください。慣性を伴うドラッグには Draggable + InertiaPlugin を使用してください。
• ✅ コンポーネントのアンマウント時や要素の削除時には、プラグインのインスタンスを元に戻してください（例：SplitTextInstance.revert()）。

禁止事項

• ❌ プラグインを登録せずに、トゥイーンまたは API で使用しないでください（gsap.registerPlugin()）。
• ❌ GSDevTools や開発専用プラグインを本番環境に含めないでください。

詳細はこちら

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