gsap.context: por qué existe y qué recoge

Antes de que existiera gsap.context(), limpiar las animaciones de un componente consistía en guardar cada tween, cada timeline y cada instancia de ScrollTrigger en una variable, mantener esa lista actualizada a mano, y llamar a kill() sobre cada una en el desmontaje. Era código aburrido, era fácil olvidarse de una pieza, y el olvido no producía ningún error visible sino una degradación lenta. El contexto elimina esa contabilidad: recoge automáticamente todo lo que se cree mientras se ejecuta una función y te da un único botón para deshacerlo todo.

Qué recoge y cuándo

gsap.context(funcion, ambito) ejecuta la función de inmediato y, mientras dura esa ejecución, apunta todo lo que GSAP crea: tweens, timelines, instancias de ScrollTrigger, Draggables, SplitText, Observers. Después devuelve un objeto con el que puedes deshacerlo todo de una vez.

import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

const ctx = gsap.context(() => {
  gsap.from(".titulo", { autoAlpha: 0, y: 40, duration: 0.8 });

  gsap.to(".fondo", {
    yPercent: -25,
    ease: "none",
    scrollTrigger: { trigger: ".seccion", scrub: 1, start: "top bottom", end: "bottom top" },
  });

  ScrollTrigger.create({
    trigger: ".seccion",
    start: "top 50%",
    onToggle: (self) => document.body.classList.toggle("oscuro", self.isActive),
  });
});

// Una sola llamada deshace las tres cosas
ctx.revert();

La palabra clave es mientras. El contexto no vigila permanentemente; solo recoge lo que ocurra durante la ejecución síncrona de la función. Un tween creado dentro de un setTimeout, dentro de un manejador de clic o dentro de una promesa que se resuelve después no queda recogido, porque para entonces la función ya terminó. Ese matiz es la causa del noventa por ciento de las fugas que sobreviven a la adopción del contexto, y tiene solución, que es lo último de esta lección.

revert frente a kill

Ambos métodos existen y no hacen lo mismo.

revert() deshace: mata las animaciones recogidas y además restaura los elementos a su estado anterior, quitando los estilos en línea que GSAP hubiera aplicado. Después de un revert(), el DOM está como si nada se hubiera animado nunca.

kill() mata las animaciones; acepta un booleano opcional que indica si además debe revertir.

La distinción importa en un caso concreto. Si vas a desmontar el componente y sus elementos van a desaparecer del DOM, da igual cuál uses. Si el componente permanece y solo quieres detener las animaciones —por ejemplo al cambiar de condición de media query—, revert() es lo que quieres, porque deja los elementos limpios para que la siguiente configuración parta de cero en lugar de heredar estilos en línea de la anterior.

La documentación es explícita sobre un punto: revert() es permanente para lo que había dentro. Las animaciones se revierten y se matan, el contexto se vacía y todo queda disponible para el recolector de basura. Pero el contexto sigue existiendo: puedes añadirle cosas nuevas después y volver a revertirlo.

Y hay una vía adicional para código de limpieza propio: si la función del contexto devuelve otra función, esa función se llama al revertir.

const ctx = gsap.context(() => {
  const observador = new ResizeObserver(() => ScrollTrigger.refresh());
  observador.observe(document.querySelector(".panel"));

  gsap.from(".tarjeta", { autoAlpha: 0, stagger: 0.1 });

  // Limpieza propia: lo que GSAP no puede saber
  return () => observador.disconnect();
});

Ese patrón es el que convierte al contexto en el punto único de limpieza del componente, y no solo de sus animaciones.

El ámbito de selectores

El segundo parámetro convierte todo el texto de selector de dentro en relativo a un elemento. Admite un elemento, texto de selector, o una referencia de React o de Angular.

const contenedor = document.querySelector("#tarjeta-7");

const ctx = gsap.context(() => {
  // ".titulo" busca SOLO dentro de #tarjeta-7
  gsap.from(".titulo", { autoAlpha: 0, y: 20 });
  gsap.from(".cuerpo p", { autoAlpha: 0, stagger: 0.05 });
}, contenedor);

Eso resuelve un problema real y molesto: en una página con veinte instancias del mismo componente, cada una necesita animar sus elementos, y sin ámbito habría que generar identificadores únicos o pasar referencias a todas partes. Con ámbito, el mismo código funciona para las veinte y cada una toca lo suyo.

El objeto de contexto expone además un selector que es una función, para cuando necesitas consultar elementos con el mismo ámbito fuera de las llamadas de GSAP.

add e ignore: lo que ocurre después

Aquí está la solución al problema que abríamos al principio. Cualquier animación que se cree después de que la función del contexto termine queda fuera de su radar. add() es la forma de meterla dentro.

Tiene dos formas. Con una función suelta como primer argumento, la ejecuta ahora mismo y recoge lo que cree. Con un nombre y una función, registra un método en el contexto que, cada vez que se llame, recogerá lo que cree.

const ctx = gsap.context((self) => {
  gsap.from(".panel", { autoAlpha: 0, duration: 0.6 });

  // Registrar un metodo que se podra llamar despues
  self.add("resaltar", (elemento) => {
    gsap.to(elemento, { scale: 1.06, duration: 0.25, yoyo: true, repeat: 1 });
  });
}, contenedor);

// Cualquier animacion creada aqui SI queda recogida por el contexto
document.querySelectorAll(".fila").forEach((fila) => {
  fila.addEventListener("mouseenter", () => ctx.resaltar(fila));
});

Fíjate en que el manejador de eventos no queda recogido: el contexto no sabe nada de escuchas del DOM. Si el componente puede desmontarse, hay que retirarlas en la función de limpieza que devuelves.

ignore() hace lo contrario: lo que se cree dentro de la función que le pases no entra en el contexto y sobrevive al revert().

gsap.context((self) => {
  gsap.from(".contenido", { autoAlpha: 0 });   // se recoge

  self.ignore(() => {
    // Una animacion global que no debe morir con este componente
    gsap.to(document.body, { backgroundColor: "#181825", duration: 0.4 });
  });
}, contenedor);

Es una válvula de escape que conviene usar poco: si algo no debe morir con el componente, normalmente es señal de que no debería crearse dentro del componente.

Lo que el contexto no sabe

Merece la pena tener la lista clara, porque marca la frontera entre lo que se limpia solo y lo que sigue siendo responsabilidad tuya:

Escuchas de eventos del DOM que hayas añadido con addEventListener. Observadores de tipo ResizeObserver, IntersectionObserver o MutationObserver. Temporizadores de setTimeout y setInterval —aunque gsap.delayedCall() sí se recoge, por ser de GSAP—. Peticiones de red pendientes. Y elementos que hayas insertado en el DOM fuera del contenedor.

Todo eso va en la función de limpieza que devuelves. El contexto es el sitio donde ponerla, no el que la escribe por ti.

const ctx = gsap.context(() => {
  const alRedimensionar = () => ScrollTrigger.refresh();
  const temporizador = setInterval(actualizarReloj, 1000);

  window.addEventListener("resize", alRedimensionar);
  gsap.from(".reloj", { autoAlpha: 0 });

  return () => {
    window.removeEventListener("resize", alRedimensionar);
    clearInterval(temporizador);
  };
}, contenedor);