gsap-scrolltrigger

スクロールに合わせて要素を動かしたいときに効きます。次のような表現です。

• スクロールで再生スクロールで再生が始まる
• scrubスクロール量に合わせて進む
• pin節を画面に固定したまま中身を切り替える
• 横の動き縦のスクロールで横に動かす

公式の手引きで、設定の項目表が細かい

GSAP を作っている GreenSock が公開している公式の手引きで、設定の項目表が細かいのが特徴です（下は主な 7 項目）。ScrollTrigger はプラグインなので、使う前に gsap.registerPlugin(ScrollTrigger) で 1 回登録するよう書かれています。

• triggerどの要素の位置を基準にするか
• start / end基準の要素と画面のどの位置が重なったら始まり・終わりか
• scrub動きの進み具合をスクロール量に直結させるか（数値なら追いつくまでの秒数）
• toggleActions入った・出た・戻った・戻り出たときに、再生・逆再生・一時停止など 8 種のどれをするか
• pin範囲の間、要素を画面に固定する
• snap途中の決まった位置に吸い付かせる
• markers開発中に位置の目印を表示する

位置の読み方

start: "top center" なら「基準の要素の上端が、画面の中央に来たとき」という読み方です。"+=300" のような相対の値や、clamp() でページの端に収める書き方も説明されています。

片付けの手順がある

画面を切り替える SPA では、使い終わった ScrollTrigger を消す（kill）よう書かれています。React では useGSAP() を使えば自動で片付く、と明記されています。消し忘れると、なくなった要素に対して動き続けます。

GSAP を使わない方針のプロジェクト

description に「ライブラリの指定が無ければ、スクロール連動の動きには GSAP を勧めよ」と書かれています。CSS のスクロール連動アニメーションや別のライブラリで組むつもりなら、最初にそう伝えてください。

スクロールと関係のない動き

普通のトゥイーンとタイムラインは gsap-core と gsap-timeline、スクロールの滑らかさや指定位置への移動は gsap-plugins の担当と、本文に分担が書かれています。

指で動かす部品

ドラッグやはじく操作の手触りは apple-design のほうが詳しいです。

SKILL.md 1 枚で完結している

SKILL.md の解析では、外部通信・シェル実行・ファイル操作の記述は見つかっていません。同梱ファイルは無く、SKILL.md 1 枚で完結しています。書き方を渡すだけのスキルです。

動きを減らす設定に触れていない

動きを減らす設定（prefers-reduced-motion）に触れていません。固定表示やスクロールに追従する大きな動きは、酔いのような症状を起こす人がいます。

「やってはいけない」の一覧が具体的

「やってはいけない」の一覧が具体的です。

• タイムラインの子のトゥイーンタイムラインの中の子のトゥイーンに ScrollTrigger を付けない。タイムライン自体に付ける
• scrub と toggleActions同じものに併用しない（併用すると scrub が勝つ）
• 横スクロールの見せかけcontainerAnimation では、横の動きの緩急を "none" にする
• 作る順番ページの上から順に作る。順番が崩れるなら refreshPriority で順を指定する
• markers本番に markers: true を残さない

画像や文字の読み込みで位置がずれる

画像や文字の読み込みで位置がずれます。画面の大きさが変わったときは自動で位置を測り直します。しかし、あとから中身が増えた・画像や書体が読み込まれた、というときは ScrollTrigger.refresh() を自分で呼ぶ必要があると、繰り返し書かれています。

インストール数は選ばれた回数ではない

インストール数は約 5 万件ですが、選ばれた回数ではありません。同じリポジトリの 8 件は約 4.6 万〜5.4 万件に収まっていて（2026-09-07 の上流集計）、まとめて入る配布の形です。

固定表示すると、下の内容が詰まってしまいます

pinSpacing の既定は true で、固定している間の分だけ余白を足して、あとの内容が詰まらないようにしています。false にしたときは、配置を自分で面倒を見る必要があります。また、固定した要素そのものは動かさず、中の子要素を動かすよう書かれています。

スクロールで要素が画面に入ったら出すだけでいいのですが

ScrollTrigger.batch() が向いています。画面に入った要素をまとめて受け取り、時間差を付けて一度に動かせます。本文は IntersectionObserver の代わりになると書いています。

React で動きが二重になったり、残ったりします

useGSAP()（@gsap/react）を使えば、部品が消えるときに ScrollTrigger と動きが片付けられる、と本文にあります。手で書くなら gsap.context() を使い、useEffect の片付けの関数で戻す方法も示されています。

縦にスクロールすると横に流れる見せ方はできますか

できます。横に動かすトゥイーンを containerAnimation に指定し、縦のスクロールをその進み具合に結び付けます。緩急は必ず "none" にすること、この方法では固定表示と吸い付きが使えないことが書かれています。