useGSAP en React: el hook que cierra el ciclo

Animar en React tiene un problema que no existe en una página sin framework: los efectos se ejecutan dos veces en desarrollo, los componentes se desmontan y se vuelven a montar sin avisar, y los nodos que animas pueden ser reemplazados por otros idénticos en cualquier rerenderizado. useGSAP() es un hook oficial que envuelve gsap.context() y resuelve las tres cosas, y su valor no está en ahorrar líneas sino en que la limpieza deja de ser algo que hay que recordar.

Instalación y forma básica

El hook vive en un paquete aparte y la documentación recomienda registrarlo como un plugin más, para evitar discrepancias entre versiones de React.

npm install gsap @gsap/react

import { useRef } from "react";
import { gsap } from "gsap";
import { useGSAP } from "@gsap/react";

gsap.registerPlugin(useGSAP);

export function Tarjeta() {
  const contenedor = useRef(null);

  useGSAP(
    () => {
      gsap.from(".titulo", { autoAlpha: 0, y: 24, duration: 0.6 });
      gsap.from(".linea", { scaleX: 0, transformOrigin: "left", duration: 0.5, delay: 0.2 });
    },
    { scope: contenedor }
  );

  return (
    <article ref={contenedor}>
      <h3 className="titulo">Nivel dios</h3>
      <span className="linea" />
    </article>
  );
}

Ese componente funciona pegado tal cual. La documentación describe el hook como un sustituto directo de useEffect o useLayoutEffect que gestiona la limpieza usando gsap.context() por debajo: todas las animaciones, ScrollTriggers, Draggables e instancias de SplitText creadas durante su ejecución se revierten cuando el componente se desmonta.

Internamente aplica la técnica del efecto isomorfo: prefiere useLayoutEffect y cae a useEffect cuando no hay window, así que es seguro en entornos con renderizado en servidor. En el enrutador de aplicación de Next hay que poner la directiva de cliente al principio del archivo.

scope: el problema de los selectores

scope recibe una referencia y hace que todo el texto de selector de dentro del hook busque solo entre los descendientes de ese elemento.

Sin él, gsap.from(".titulo", ...) afecta a todos los elementos con esa clase de la página. Con veinte tarjetas en pantalla, el componente número tres anima los títulos de las veinte. El fallo es tan visual que se detecta enseguida, pero la solución habitual sin el hook —generar identificadores únicos o una referencia por elemento— ensucia mucho el componente.

Con scope, el mismo código funciona para las veinte instancias y cada una toca lo suyo. Es probablemente la opción que más justifica usar el hook.

dependencies y revertOnUpdate

El segundo parámetro puede ser el array de dependencias o el objeto de configuración. Las tres claves válidas son scope, dependencies y revertOnUpdate, y no hay más.

// Sin dependencias: se ejecuta una vez al montar
useGSAP(() => { /* ... */ }, { scope: contenedor });

// Con dependencias: se vuelve a ejecutar cuando cambian
useGSAP(() => { /* ... */ }, { scope: contenedor, dependencies: [abierto] });

// Forma corta cuando no necesitas mas configuracion
useGSAP(() => { /* ... */ }, [abierto]);

Aquí está el detalle que hay que entender bien. Por defecto, cuando una dependencia cambia, la función se vuelve a ejecutar pero lo anterior no se revierte: la reversión ocurre solo al desmontar, y la función de limpieza que devuelvas tampoco se ejecuta hasta entonces. Es deliberado, porque en muchos casos quieres que lo anterior siga vivo y solo añadir algo nuevo.

Con revertOnUpdate: true, cada cambio de dependencia revierte el contexto anterior y ejecuta tu función de limpieza antes de volver a ejecutar la función principal.

useGSAP(
  () => {
    ScrollTrigger.create({
      trigger: contenedor.current,
      start: "top 70%",
      onEnter: () => marcarVisto(id),
    });
  },
  { scope: contenedor, dependencies: [id], revertOnUpdate: true }
);

La regla práctica: si la función crea instancias que deberían existir en lugar de las anteriores —ScrollTriggers, Draggables, SplitText, Observers—, quieres revertOnUpdate: true. Si solo lanza un tween que sustituye al anterior por sobrescritura, no hace falta.

contextSafe: lo que se crea después

El contexto recoge lo que se cree durante la ejecución de la función. Todo lo que ocurra después —un manejador de clic, un temporizador, una promesa que se resuelve, una respuesta de red— queda fuera: no se recoge, no se limpia, y su texto de selector no usa el ámbito.

contextSafe() convierte una función cualquiera en una versión que sí queda dentro. Hay dos formas de acceder a ella.

Dentro del hook, llega como segundo argumento:

useGSAP(
  (contexto, contextSafe) => {
    const alPulsar = contextSafe(() => {
      gsap.to(".panel", { x: 200, duration: 0.4 });
    });

    const boton = contenedor.current.querySelector(".abrir");
    boton.addEventListener("click", alPulsar);

    // La escucha SI hay que retirarla a mano
    return () => boton.removeEventListener("click", alPulsar);
  },
  { scope: contenedor }
);

Fuera del hook, viene en el objeto que devuelve, junto con context:

export function Panel() {
  const contenedor = useRef(null);
  const { contextSafe } = useGSAP({ scope: contenedor });

  const abrir = contextSafe(() => {
    gsap.to(".contenido", { height: "auto", duration: 0.4 });
  });

  return (
    <div ref={contenedor}>
      <button onClick={abrir}>Abrir</button>
      <div className="contenido" />
    </div>
  );
}

Fíjate en que la segunda forma pasa el objeto de configuración como primer argumento, sin función. Es la forma documentada para cuando solo quieres contextSafe.

Y un aviso que la propia documentación subraya: envolver la función en contextSafe recoge las animaciones, pero no retira la escucha de eventos. Si la añadiste con addEventListener, sigue siendo tuya y va en la función de limpieza. Con un onClick de JSX no hay problema, porque React la retira sola.

Errores frecuentes

Los selectores tocan otros componentes. Falta scope.

La animación se duplica en desarrollo y no en producción. Es el modo estricto. Si ocurre con el hook puesto, revisa si estás creando algo fuera de su función.

Una animación creada en un clic no se limpia. Falta contextSafe.

Un gsap.from() deja el elemento en un sitio raro. Doble ejecución sin reversión entre medias. El hook lo arregla; si persiste, comprueba que no estás creando la animación fuera de él.

Flip no anima nada tras un rerenderizado. El estado apunta a nodos que React ha sustituido. Hay que pasar targets y poner data-flip-id.