gsap-frameworks

GSAP con Vue, Svelte y Otros Frameworks

Cuándo Usar Esta Skill

Aplícala al escribir o revisar código de GSAP en Vue (o Nuxt), Svelte (o SvelteKit) u otros frameworks de componentes que usen un ciclo de vida (montado/desmontado). Para React específicamente, usa gsap-react (hook useGSAP, gsap.context()).

Skills relacionadas: para tweens y timelines usa gsap-core y gsap-timeline; para animaciones basadas en scroll usa gsap-scrolltrigger; para React usa gsap-react.

Principios (Todos los Frameworks)

• Crear tweens y ScrollTriggers después de que el DOM del componente esté disponible (por ejemplo, onMounted, onMount).
• Matar o revertir en la limpieza de desmontaje (o equivalente) para que nada se ejecute en nodos desmontados y no haya fugas.
• Limitar selectores al elemento raíz del componente para que .box y similares solo coincidan con elementos dentro de ese componente, no con el resto de la página.

Vue 3 (Composition API)

Consulta examples/vue/ para un proyecto Vite + Vue 3 ejecutable que demuestra estos patrones.

Usa onMounted para ejecutar GSAP después de que el componente esté en el DOM. Usa onUnmounted para limpiar.

import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // una vez por app, por ejemplo en 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) — pasa la referencia del contenedor (por ejemplo container.value) como segundo argumento para que selectores como .item tengan ámbito dentro de esa raíz. Todas las animaciones y ScrollTriggers creados dentro del callback son rastreados y revertidos cuando se llama a ctx.revert().
• ✅ onUnmounted — siempre llama a ctx.revert() para que los tweens y ScrollTriggers se maten y los estilos en línea se reviertan.

Vue 3 (script setup)

Misma idea con <script setup> y 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">Caja</div>
    <div class="item">Elemento</div>
  </div>
</template>

Nuxt 4

Consulta examples/nuxt/ para un proyecto Nuxt 4 ejecutable con registro de plugins, carga diferida y patrones seguros para SSR.

Usa un composable reutilizable para registrar plugins de GSAP y también para cargar de forma diferida plugins que no se usen extensamente en tu aplicación:

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

// Para cargar dinámicamente todos los plugins de GSAP
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;

// Resuelve el tipo del módulo para una clave dada, luego toma la exportación nombrada que coincide con la clave
// esto permite tener definiciones de tipo para el autocompletado en tu editor de código
type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];

export default function () {
  // Registra todos los plugins de GSAP que quieras en este punto
  gsap.registerPlugin(ScrollTrigger);

  /*
    Si quieres cargar de forma diferida algunos plugins que no
    se usan ampliamente en tu app (por ejemplo solo en un par
    de componentes o una sola ruta), puedes usar este método
  */
  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,
  };
}

Accede desde los componentes con useGSAP():

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

• ✅ useGSAP() proporciona acceso tipado a la instancia de gsap y al método de carga diferida.
• ✅ Carga diferida de cualquier plugin (SplitText, MorphSVG, etc.) que no se use ampliamente en tu app para reducir el tamaño inicial del bundle.
• ✅ Usa gsap.context(scope) y onUnmounted → ctx.revert() en los componentes, igual que en Vue 3.

Svelte

Usa onMount para ejecutar GSAP después de que el DOM esté listo. Usa la función de limpieza retornada de onMount (o rastrea el contexto y limpia en un bloque reactivo / destroy del componente) para revertir. Svelte 5 usa un ciclo de vida diferente; el mismo principio aplica: crear en "montado" y revertir en "destruido".

<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">Caja</div>
  <div class="item">Elemento</div>
</div>

• ✅ bind:this={container} — obtén una referencia al elemento raíz para pasarla a gsap.context(scope).
• ✅ return () => ctx.revert() — onMount en Svelte puede retornar una función de limpieza; llama a ctx.revert() allí para que la limpieza se ejecute cuando el componente se destruya.

Limitando Selectores

No uses selectores globales que puedan coincidir con elementos fuera del componente actual. Siempre pasa el scope (elemento contenedor o ref) como segundo argumento a gsap.context(callback, scope) para que cualquier selector ejecutado dentro del callback se limite a ese subárbol.

• ✅ gsap.context(() => { gsap.to(".box", ...) }, containerRef) — .box solo se busca dentro de containerRef.
• ❌ Ejecutar gsap.to(".box", ...) sin un ámbito de contexto en un componente puede afectar otras instancias o el resto de la página.

Limpieza de ScrollTrigger

Las instancias de ScrollTrigger se crean cuando usas la configuración scrollTrigger en un tween/timeline o ScrollTrigger.create(). Están incluidas en gsap.context() y se revierten cuando llamas a ctx.revert(). Por lo tanto:

• Crea los ScrollTriggers dentro del mismo callback de gsap.context() que uses para los tweens.
• Llama a ScrollTrigger.refresh() después de cambios de diseño (por ejemplo, después de cargar datos) que afecten las posiciones de los triggers; en Vue/Svelte eso suele ocurrir después de que el DOM se actualice (por ejemplo, nextTick en Vue, tick en Svelte, o después de una carga de contenido asíncrono).

Cuándo Crear vs Matar

Ciclo de vida	Acción
Montado	Crea tweens y ScrollTriggers dentro de gsap.context(scope).
Desmontar / Destruir	Llama a ctx.revert() para que todas las animaciones y ScrollTriggers en ese contexto se maten y se reviertan los estilos en línea.

No crees animaciones de GSAP en el setup del componente o en un script síncrono de nivel superior que se ejecute antes de que exista el elemento raíz. Espera a onMounted / onMount (o equivalente) para que la referencia del contenedor esté en el DOM.

No Hacer

• ❌ Crear tweens o ScrollTriggers antes de que el componente esté montado (por ejemplo, en setup sin onMounted); los nodos del DOM pueden no existir todavía.
• ❌ Usar cadenas de selectores sin un scope (pasa el contenedor a gsap.context() como segundo argumento) para que los selectores no coincidan con elementos fuera del componente.
• ❌ Omitir la limpieza; siempre llama a ctx.revert() en onUnmounted / el retorno de onMount para que las animaciones y ScrollTriggers se maten cuando el componente se destruya.
• ❌ Registrar plugins dentro del cuerpo de un componente que se ejecuta en cada render (no causa daño, solo es un desperdicio); regístralos una vez a nivel de app.

Aprende Más

• Skill gsap-react para patrones específicos de React (useGSAP, contextSafe).