Vue、Svelte、その他フレームワークを使用した GSAP

このスキルを使用する時期

Vue（または Nuxt）、Svelte（または SvelteKit）、またはマウント/アンマウントのライフサイクルを使用する他のコンポーネントフレームワークで GSAP コードを作成・レビューする場合に適用します。React の場合は gsap-react（useGSAP フック、gsap.context()）を使用してください。

関連スキル: トゥイーンとタイムラインには gsap-core と gsap-timeline を使用してください。スクロールベースのアニメーションには gsap-scrolltrigger を使用してください。React には gsap-react を使用してください。

原則（全フレームワーク共通）

• トゥイーンと ScrollTrigger を作成する のは、コンポーネントの DOM が利用可能になった後（例：onMounted、onMount）です。
• アンマウント（または同等の処理）時のクリーンアップで、それらをキルまたはリバートしてください。これにより、分離されたノードでは何も実行されず、リークが発生しません。
• セレクターをコンポーネントルートにスコープするので、.box のようなセレクターはそのコンポーネント内の要素のみと一致し、ページの残りの部分とは一致しません。

Vue 3（Composition API）

これらのパターンを実演する実行可能な Vite + Vue 3 プロジェクトについては、examples/vue/ を参照してください。

コンポーネントが DOM に配置された後に GSAP を実行するには onMounted を使用します。クリーンアップするには onUnmounted を使用します。

import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js

export default {
  setup() {
    const container = ref(null);
    let ctx;

    onMounted(() => {
      if (!container.value) return;
      ctx = gsap.context(() => {
        gsap.to(".box", { x: 100, duration: 0.6 });
        gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
      }, container.value);
    });

    onUnmounted(() => {
      ctx?.revert();
    });

    return { container };
  },
};

• ✅ gsap.context(scope) — コンテナ参照（例：container.value）を第 2 引数として渡すことで、.item のようなセレクターはそのルートにスコープされます。コールバック内で作成されたすべてのアニメーションと ScrollTrigger は追跡され、ctx.revert() が呼ばれるとリバートされます。
• ✅ onUnmounted — 常に ctx.revert() を呼び出すことで、トゥイーンと ScrollTrigger がキルされ、インラインスタイルがリバートされます。

Vue 3（script setup）

<script setup> と refs を使用した同じアイデア：

<script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

const container = ref(null);
let ctx;

onMounted(() => {
  if (!container.value) return;
  ctx = gsap.context(() => {
    gsap.to(".box", { x: 100 });
    gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
  }, container.value);
});

onUnmounted(() => {
  ctx?.revert();
});
</script>

<template>
  <div ref="container">
    <div class="box">Box</div>
    <div class="item">Item</div>
  </div>
</template>

Nuxt 4

プラグイン登録、遅延ロード、および SSR セーフなパターンを使用した実行可能な Nuxt 4 プロジェクトについては、examples/nuxt/ を参照してください。

再利用可能なコンポーザブルを使用して GSAP プラグインを登録し、アプリケーション内で広く使用されていないプラグインを遅延ロードします：

// composables/useGSAP.ts
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

const PLUGINS = [
  "CSSRulePlugin",
  "CustomBounce",
  "CustomEase",
  "CustomWiggle",
  "Draggable",
  "DrawSVGPlugin",
  "EaselPlugin",
  "EasePack",
  "Flip",
  "GSDevTools",
  "InertiaPlugin",
  "MorphSVGPlugin",
  "MotionPathHelper",
  "MotionPathPlugin",
  "Observer",
  "Physics2DPlugin",
  "PhysicsPropsPlugin",
  "PixiPlugin",
  "ScrambleTextPlugin",
  "ScrollSmoother",
  "ScrollToPlugin",
  "ScrollTrigger",
  "SplitText",
  "TextPlugin",
] as const;

type Plugins = (typeof PLUGINS)[number];

// In order to dynamically load all the GSAP plugins
const pluginMap = {
  CustomEase: () => import("gsap/CustomEase"),
  Draggable: () => import("gsap/Draggable"),
  CSSRulePlugin: () => import("gsap/CSSRulePlugin"),
  EaselPlugin: () => import("gsap/EaselPlugin"),
  EasePack: () => import("gsap/EasePack"),
  Flip: () => import("gsap/Flip"),
  MotionPathPlugin: () => import("gsap/MotionPathPlugin"),
  Observer: () => import("gsap/Observer"),
  PixiPlugin: () => import("gsap/PixiPlugin"),
  ScrollToPlugin: () => import("gsap/ScrollToPlugin"),
  ScrollTrigger: () => import("gsap/ScrollTrigger"),
  TextPlugin: () => import("gsap/TextPlugin"),
  DrawSVGPlugin: () => import("gsap/DrawSVGPlugin"),
  Physics2DPlugin: () => import("gsap/Physics2DPlugin"),
  PhysicsPropsPlugin: () => import("gsap/PhysicsPropsPlugin"),
  ScrambleTextPlugin: () => import("gsap/ScrambleTextPlugin"),
  CustomBounce: () => import("gsap/CustomBounce"),
  CustomWiggle: () => import("gsap/CustomWiggle"),
  GSDevTools: () => import("gsap/GSDevTools"),
  InertiaPlugin: () => import("gsap/InertiaPlugin"),
  MorphSVGPlugin: () => import("gsap/MorphSVGPlugin"),
  MotionPathHelper: () => import("gsap/MotionPathHelper"),
  ScrollSmoother: () => import("gsap/ScrollSmoother"),
  SplitText: () => import("gsap/SplitText"),
} as const;

type PluginMap = typeof pluginMap;
type Plugins = keyof PluginMap;

// Resolves the module type for a given key, then picks the named export matching the key
// this allows to have the type definitions for autocomplete in your code editor
type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];

export default function () {
  // Register all the GSAP Plugins you want at this point
  gsap.registerPlugin(ScrollTrigger);

  /*
    If you want to lazy load some of the plugins that are
    not widely used in your app (for example in just a couple
    of components or a single route), you can use this method
  */
  async function lazyLoadPlugin<K extends Plugins>(plugin: K): Promise<PluginExport<K>> {
    const loader = pluginMap[plugin];
    const m = await loader();
    const p = (m as any)[plugin];
    gsap.registerPlugin(p);
    return p;
  }

  return {
    gsap,
    ScrollTrigger,
    lazyLoadPlugin,
  };
}

useGSAP() 経由でコンポーネント内でアクセス：

const { gsap, ScrollTrigger, lazyLoadPlugin } = useGSAP();

• ✅ useGSAP() は gsap インスタンスと遅延ロードメソッドへの型付きアクセスを提供します。
• ✅ アプリ内で広く使用されていないプラグイン（SplitText、MorphSVG など）を遅延ロードして初期バンドルサイズを削減します。
• ✅ コンポーネント内で gsap.context(scope) と onUnmounted → ctx.revert() を使用します（Vue 3 と同じ）。

Svelte

DOM の準備ができた後に GSAP を実行するには onMount を使用します。onMount から返されたクリーンアップ関数を使用するか（またはコンテキストを追跡し、リアクティブブロック/コンポーネント破棄でクリーンアップ）、リバートします。Svelte 5 は異なるライフサイクルを使用します。同じ原則が適用されます：「mounted」で作成し、「destroyed」でリバートします。

<script>
  import { onMount } from "svelte";
  import { gsap } from "gsap";
  import { ScrollTrigger } from "gsap/ScrollTrigger";

  let container;

  onMount(() => {
    if (!container) return;
    const ctx = gsap.context(() => {
      gsap.to(".box", { x: 100 });
      gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
    }, container);
    return () => ctx.revert();
  });
</script>

<div bind:this={container}>
  <div class="box">Box</div>
  <div class="item">Item</div>
</div>

• ✅ bind:this={container} — ルート要素への参照を取得し、gsap.context(scope) に渡せます。
• ✅ return () => ctx.revert() — Svelte の onMount はクリーンアップ関数を返すことができます。そこで ctx.revert() を呼び出すことで、コンポーネントが破棄されるとクリーンアップが実行されます。

セレクターのスコープ指定

現在のコンポーネント外の要素と一致する可能性があるグローバルセレクターを使用しないでください。常にスコープ（コンテナ要素または ref）を gsap.context(callback, scope) の第 2 引数として渡すことで、コールバック内で実行されるセレクターはそのサブツリーに限定されます。

• ✅ gsap.context(() => { gsap.to(".box", ...) }, containerRef) — .box は containerRef 内でのみ検索されます。
• ❌ コンテキストスコープなしでコンポーネント内で gsap.to(".box", ...) を実行すると、他のインスタンスまたはページの残りの部分に影響を与える可能性があります。

ScrollTrigger のクリーンアップ

ScrollTrigger インスタンスは、トゥイーン/タイムラインで scrollTrigger 設定を使用するか、ScrollTrigger.create() を使用するときに作成されます。それらは gsap.context() に含まれており、ctx.revert() を呼び出すとリバートされます。したがって：

• トゥイーンに使用するのと同じ gsap.context() コールバック内で ScrollTrigger を作成します。
• レイアウト変更後（例：データロード後）に ScrollTrigger.refresh() を呼び出して、トリガーポジションに影響を与えます。Vue/Svelte では、DOM が更新された後（例：Vue では nextTick、Svelte では tick、または非同期コンテンツロード後）を意味することがよくあります。

作成とキルのタイミング

ライフサイクル	アクション
マウント	gsap.context(scope) 内でトゥイーンと ScrollTrigger を作成します。
アンマウント/破棄	ctx.revert() を呼び出すことで、そのコンテキスト内のすべてのアニメーションと ScrollTrigger がキルされ、インラインスタイルがリバートされます。

コンポーネントの setup またはルート要素が存在する前に実行される同期的なトップレベルスクリプトで GSAP アニメーションを作成しないでください。onMounted / onMount（または同等の処理）を待ってから、コンテナ ref が DOM に配置されるようにしてください。

避けるべきこと

• ❌ コンポーネントがマウントされる前にトゥイーンまたは ScrollTrigger を作成する（例：onMounted なしで setup で）。DOM ノードがまだ存在しない可能性があります。
• ❌ スコープのないセレクター文字列を使用する（gsap.context() の第 2 引数としてコンテナを渡して）。セレクターがコンポーネント外の要素と一致しないようにします。
• ❌ クリーンアップをスキップする。常に onUnmounted / onMount の戻り値で ctx.revert() を呼び出すことで、コンポーネントが破棄されるときにアニメーションと ScrollTrigger がキルされます。
• ❌ すべてのレンダーで実行されるコンポーネント本体内でプラグインを登録する（害はありませんが、ただ無駄です）。アプリレベルで 1 回登録します。

さらに詳しく

• React 固有のパターンについては gsap-react スキル（useGSAP、contextSafe）を参照してください。