gsap-frameworks

GSAP mit Vue, Svelte und anderen Frameworks

Wann diese Fähigkeit anwenden

Verwende sie, wenn GSAP-Code in Vue (oder Nuxt), Svelte (oder SvelteKit) oder anderen Komponenten-Frameworks mit einem Lifecycle (mounted/unmounted) geschrieben oder überprüft wird. Für React verwende stattdessen gsap-react (useGSAP-Hook, gsap.context()).

Verwandte Fähigkeiten: Für Tweens und Timelines verwende gsap-core und gsap-timeline; für scrollbasierte Animationen gsap-scrolltrigger; für React gsap-react.

Prinzipien (alle Frameworks)

• Erstelle Tweens und ScrollTrigger nachdem das DOM der Komponente verfügbar ist (z. B. onMounted, onMount).
• Kill oder revertiere sie beim Unmount (oder entsprechendem Cleanup), damit nichts auf gelöschten Knoten läuft und keine Speicherlecks entstehen.
• Grenze Selektoren auf die Komponentenwurzel ein, sodass .box und ähnliche nur Elemente innerhalb dieser Komponente treffen, nicht den Rest der Seite.

Vue 3 (Composition API)

Siehe examples/vue/ für ein ausführbares Vite + Vue 3-Projekt, das diese Muster demonstriert.

Verwende onMounted, um GSAP auszuführen, nachdem die Komponente im DOM ist. Verwende onUnmounted für die Bereinigung.

import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // einmal pro App, z. B. 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) – Übergib die Container-Referenz (z. B. container.value) als zweites Argument, damit Selektoren wie .item auf diese Wurzel beschränkt sind. Alle im Callback erstellten Animationen und ScrollTrigger werden nachverfolgt und beim Aufruf von ctx.revert() rückgängig gemacht.
• ✅ onUnmounted – Rufe immer ctx.revert() auf, damit Tweens und ScrollTrigger gestoppt und Inline-Stile zurückgesetzt werden.

Vue 3 (script setup)

Gleiches Prinzip mit <script setup> und 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

Siehe examples/nuxt/ für ein ausführbares Nuxt 4-Projekt mit Plugin-Registrierung, Lazy Loading und SSR-sicheren Mustern.

Verwende ein wiederverwendbares Composables, um GSAP-Plugins zu registrieren und Plugins, die nicht umfangreich in der Anwendung genutzt werden, lazy zu laden:

// 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];

// Zum dynamischen Laden aller 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;

// Ermittelt den Modul-Typ für einen gegebenen Schlüssel und wählt dann den benannten Export mit passendem Namen aus.
// Dies ermöglicht die Typdefinitionen für die Autovervollständigung im Editor.
type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];

export default function () {
  // Registriere hier alle GSAP-Plugins, die du möchtest
  gsap.registerPlugin(ScrollTrigger);

  /*
    Wenn du Plugins, die in deiner App nicht weit verbreitet sind (z. B. nur in einigen wenigen Komponenten
    oder einer einzigen Route), lazy laden möchtest, kannst du diese Methode verwenden.
  */
  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,
  };
}

Zugriff in Komponenten über useGSAP():

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

• ✅ useGSAP() bietet typisierten Zugriff auf die GSAP-Instanz und die Lazy-Load-Methode.
• ✅ Lade jedes Plugin lazy (SplitText, MorphSVG usw.), das in der App nicht weit verbreitet ist, um die anfängliche Bündelgröße zu reduzieren.
• ✅ Verwende gsap.context(scope) und onUnmounted → ctx.revert() in Komponenten, wie bei Vue 3.

Svelte

Verwende onMount, um GSAP auszuführen, nachdem das DOM bereit ist. Verwende die zurückgegebene Cleanup-Funktion von onMount (oder verfolge den Kontext und bereinige in einem reaktiven Block / beim Zerstören der Komponente), um rückgängig zu machen. Svelte 5 verwendet einen anderen Lifecycle; dasselbe Prinzip gilt: Erstellen im „mounted” und Rückgängig machen im „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} – Erhalte eine Referenz auf das Wurzelelement, um es an gsap.context(scope) zu übergeben.
• ✅ return () => ctx.revert() – Sveltes onMount kann eine Cleanup-Funktion zurückgeben; rufe ctx.revert() dort auf, damit die Bereinigung beim Zerstören der Komponente ausgeführt wird.

Selektoren eingenzen

Verwende keine globalen Selektoren, die Elemente außerhalb der aktuellen Komponente treffen können. Übergib immer den scope (Container-Element oder Ref) als zweites Argument an gsap.context(callback, scope), sodass jeder im Callback ausgeführte Selektor auf diesen Teilbaum beschränkt ist.

• ✅ gsap.context(() => { gsap.to(".box", ...) }, containerRef) – .box wird nur innerhalb von containerRef gesucht.
• ❌ Die Ausführung von gsap.to(".box", ...) ohne einen Kontext-Scope in einer Komponente kann andere Instanzen oder den Rest der Seite beeinflussen.

ScrollTrigger-Bereinigung

ScrollTrigger-Instanzen werden erstellt, wenn du die scrollTrigger-Konfiguration bei einem Tween/Timeline oder ScrollTrigger.create() verwendest. Sie sind in gsap.context() enthalten und werden beim Aufruf von ctx.revert() rückgängig gemacht. Also:

• Erstelle ScrollTrigger innerhalb desselben gsap.context()-Callbacks, das du für Tweens verwendest.
• Rufe ScrollTrigger.refresh() nach Layout-Änderungen (z. B. nach Datenladungen) auf, die die Auslöser-Positionen beeinflussen; in Vue/Svelte geschieht das oft nach DOM-Updates (z. B. nextTick in Vue, tick in Svelte oder nach asynchronem Content-Laden).

Wann erstellen vs. killen

Lifecycle	Aktion
Mounted	Erstelle Tweens und ScrollTrigger innerhalb von gsap.context(scope).
Unmount / Destroy	Rufe ctx.revert() auf, sodass alle Animationen und ScrollTrigger in diesem Kontext gestoppt und Inline-Stile zurückgesetzt werden.

Erstelle GSAP-Animationen nicht im setup der Komponente oder in einem synchronen Top-Level-Script, das vor der Existenz des Wurzelelements ausgeführt wird. Warte auf onMounted / onMount (oder Äquivalent), damit die Container-Referenz im DOM ist.

Nicht tun

• ❌ Erstelle Tweens oder ScrollTrigger, bevor die Komponente gemountet ist (z. B. im setup ohne onMounted); die DOM-Knoten könnten noch nicht existieren.
• ❌ Verwende Selektor-Strings ohne einen scope (übergib den Container als zweites Argument an gsap.context()), damit Selektoren keine Elemente außerhalb der Komponente treffen.
• ❌ Überspringe die Bereinigung; rufe immer ctx.revert() in onUnmounted / dem Rückgabewert von onMount auf, damit Animationen und ScrollTrigger beim Zerstören der Komponente gestoppt werden.
• ❌ Registriere Plugins innerhalb eines Komponentenrumpfs, der bei jedem Rendern ausgeführt wird (es schadet nicht, ist aber unnötig); registriere einmal auf App-Ebene.

Mehr erfahren

• gsap-react-Fähigkeit für React-spezifische Muster (useGSAP, contextSafe).