gsap-react

gsap-react の概要

gsap-react は何のためのものか

gsap-react は、React および Next.js のような React ベースのフレームワーク向けに用意された GSAP 公式スキルです。useGSAP()、スコープ付きセレクタ、gsap.context()、自動クリーンアップといった、React で安全にアニメーションを作るためのパターンを使えるようにします。コンポーネント内にモーションを足したいときに、再レンダリング、アンマウント、DOM セレクションの不具合といった問題でつまずきたくないなら、gsap-react スキルを使うのが適しています。

どんな人に向いているか

このスキルは、すでに React を理解していて、汎用的なアニメーション入門ではなく、信頼できる実装方法を知りたいフロントエンドエンジニア向けです。特に、React アプリで GSAP を使うべきか判断したいとき、ルート変更後にアニメーションが壊れるとき、あるいは gsap-react のインストールと統合フローを確認したいときに役立ちます。

何が違うのか

最大の価値は、React 向けの安全性にあります。単純な useEffect() でアニメーションを書いて手動で後始末するのではなく、gsap-react は useGSAP() とスコープ付きターゲットへ導き、アニメーションの挙動を予測しやすくします。さらに、導入を妨げがちな典型的ミス、つまりスコープのないセレクタ、プラグイン登録忘れ、SSR に関する混乱も避けやすくなります。

gsap-react スキルの使い方

GSAP と React パッケージをインストールする

gsap-react のインストールでは、アプリに両方のパッケージを追加します。

npm install gsap
npm install @gsap/react

その後、useGSAP() や他の GSAP コードを使う前にプラグインを登録します。

import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);

登録を省略すると、フックは期待どおりに動作しません。

曖昧な目的を、そのまま使えるプロンプトに変える

gsap-react をうまく使うには、「もっと見栄えを良くして」ではなく、具体的なアニメーションの目的から始めるのがコツです。含めるべき要素は、コンポーネントの種類、何をアニメーションさせるか、いつ開始するか、繰り返すかどうか、そしてルート変更後も維持したいのか、アンマウント時にクリーンアップしたいのか、です。

強いプロンプトの例:

• 「Next.js のクライアントコンポーネントで、マウント時に 3 枚のカードがスライドインするアニメーションを、このコンテナ内にスコープして実装して」
• 「この useEffect() の GSAP アニメーションを、クリーンアップ付きの useGSAP() と refs に書き換えて」
• 「ホバーとスクロールトリガーのモーションを追加しつつ、セレクタはコンポーネント内にスコープしたままにして」

最初に読むべきファイル

まず SKILL.md を読み、その次にリポジトリ内で挙動や制約を定義している箇所を確認します。このスキルでは読むべき範囲が短いので、最初にコア指示を押さえ、必要ならリンクされた例や周辺ドキュメントに進むのが効率的です。gsap-react では、主な判断ポイントは When to Use This Skill、Installation、そして Prefer the useGSAP() Hook の各セクションです。

React 安全なワークフローを使う

基本の流れは、useGSAP を import し、プラグインを登録し、ref を作成し、セレクタをその ref にスコープし、アニメーションコードをフック内に置く、という形です。ドキュメント全体に効くセレクタや、スコープされていないタイムラインを直接使うより、この流れを優先してください。後から発火するコールバックが必要な場合は、遅延したインタラクションでも正しくクリーンアップできるように contextSafe を使います。

gsap-react スキルの FAQ

React のすべての GSAP アニメーションで gsap-react は必要か

いいえ。アニメーションが小規模で、すでにスタック内の別の仕組みで十分に解決できるなら、このスキルは不要かもしれません。React や Next.js でコンポーネントのライフサイクル、クリーンアップ、スコープ付き DOM ターゲティング、フレームワーク固有の挙動に触れるコードなら、gsap-react を使う価値があります。

一般的なプロンプトと何が違うのか

通常のプロンプトでも動くアニメーションコードは出せますが、gsap-react は本番運用で効いてくる React 統合ルール、つまりプラグイン登録、useGSAP()、スコープ付きセレクタ、クリーンアップの扱いを明示的に押さえます。その分、デバッグ時間を減らし、実際のアプリコードでも再利用しやすい出力になります。

gsap-react は初心者向けか

はい、コンポーネントと、やりたいモーションを説明できるなら使えます。アニメーション理論を学ぶための入門講座ではなく、ざっくりした UI イメージから安全な React コードに落とし込むための実践的な gsap-react ガイドです。初心者が最も良い結果を得られるのは、コンポーネント構造と、想定しているトリガーを具体的に伝えたときです。

使わないほうがいいのはいつか

非 React フレームワーク向けには gsap-react を選ばないでください。また、ライブラリ非依存のアニメーション回答が必要な場合にも向きません。Vue、Svelte、そのほかのスタックでは、各フレームワーク向けの GSAP スキルを使ってください。必要なのが基本的な tween や timeline の構文だけなら、別の GSAP スキルのほうが合っている場合があります。

gsap-react スキルを改善する方法

意図だけでなく、構造を渡す

gsap-react の出力を良くする最大のポイントは、具体性です。コンポーネントのマークアップ、すでに持っているセレクタや refs、正確な発火条件を伝えてください。「hero をアニメーションして」だけでは弱いですが、「タイトルをフェードイン、CTA をスライド、最初の描画時に feature カードを stagger で表示して」なら、実用的なコードを出すのに十分な情報になります。

実装を左右する制約を先に伝える

SSR、ルート遷移、prefers-reduced-motion、クリーンアップ要件は、早い段階で明示してください。これらの制約によって、useGSAP() を使うべきか、クライアントコンポーネントにするべきか、refs でスコープするべきか、別のアニメーション手法に切り替えるべきかが決まります。アプリが Next.js なら、プロンプト内でその旨をはっきり書くのが重要です。

最初の結果はスコープのミスを確認する

よくある失敗は、スコープのないセレクタ、早すぎるタイミングで走るアニメーション、コンポーネントのアンマウントを無視したコードです。最初の出力が .box のような広いセレクタをスコープなしで使っているなら、ref スコープに書き直すよう依頼してください。後から発火するコールバックがあるなら、次のやり取りで contextSafe の対応を求めます。

欲しいモーションに合わせて一つずつ調整する

最初の実装のあとで、毎回ひとつの変数だけを変えて詰めていくのが効果的です。例えば、タイミング、イージング、stagger、トリガー、クリーンアップの挙動などです。gsap-react の良い使い方は、まずベースのアニメーションを実装し、コンポーネント内で動作確認し、その後に「モバイルでは控えめにして」「トリガーをホバーのみにして」といった個別調整を依頼する流れです。