Los callbacks y el objeto self que reciben

toggleActions cubre el caso en que lo único que quieres es controlar una animación de GSAP. En cuanto necesitas cambiar el estado de tu aplicación, reproducir un vídeo, cargar datos o reaccionar a la velocidad del scroll, hay que bajar un piso. Los callbacks de ScrollTrigger son ese piso, y todos comparten una firma idéntica: reciben un único parámetro, la propia instancia, que trae consigo el estado completo del sistema en ese instante. Aprender qué hay dentro de ese objeto es aprender todo lo que ScrollTrigger sabe.

Los callbacks de posición

Los cuatro primeros se corresponden exactamente con las cuatro posiciones de toggleActions: onEnter, onLeave, onEnterBack y onLeaveBack. Se disparan al cruzar cada frontera en cada sentido, y no hay diferencia semántica alguna con las palabras clave; simplemente puedes ejecutar código arbitrario en vez de una acción predefinida.

ScrollTrigger.create({
  trigger: ".video-seccion",
  start: "top 70%",
  end: "bottom 30%",
  onEnter: () => video.play(),
  onLeave: () => video.pause(),
  onEnterBack: () => video.play(),
  onLeaveBack: () => video.pause(),
});

Ese patrón —dos pares idénticos— aparece tan a menudo que existe un quinto callback pensado justo para él. onToggle se dispara cuando la instancia cambia de inactiva a activa o al revés, y como el objeto que recibe trae isActive, un solo callback sustituye a los cuatro.

ScrollTrigger.create({
  trigger: ".video-seccion",
  start: "top 70%",
  end: "bottom 30%",
  onToggle: (self) => (self.isActive ? video.play() : video.pause()),
});

Hay un matiz que conviene conocer porque produce un fallo real y silencioso: si el usuario hace scroll tan rápido que en un solo tick la posición pasa de antes del start a después del end, la instancia nunca llegó a estar activa, el estado no cambió, y onToggle no se dispara. Los cuatro callbacks de posición sí, porque miden cruces de frontera y ambas fronteras se cruzaron. Si tu lógica tiene que ejecutarse sí o sí en cada paso, usa los cuatro; si describe un estado, usa onToggle.

El sexto es onUpdate, y se dispara cada vez que cambia el progress, es decir, en cada tick en que la barra de scroll se ha movido dentro del intervalo. Es el callback de grano fino, y también el más fácil de usar mal.

El objeto self, propiedad a propiedad

Todos los callbacks reciben la instancia como único parámetro. Estas son sus propiedades, y ninguna es de adorno:

Y sus métodos más útiles: getVelocity() devuelve la velocidad del scroll en píxeles por segundo, con signo; scroll() lee o escribe la posición de la barra del scroller asociado; refresh() recalcula solo esa instancia; getTween() devuelve el tween interno del scrub, o el del snap si le pasas true; labelToScroll(nombre) traduce una etiqueta de la timeline asociada a la posición de scroll que la produce; previous() y next() devuelven las instancias vecinas en el orden de refresco.

ScrollTrigger.create({
  trigger: ".seccion",
  start: "top bottom",
  end: "bottom top",
  onUpdate: (self) => {
    // Inclinar un elemento segun lo rapido que se este haciendo scroll
    const skew = gsap.utils.clamp(-12, 12, self.getVelocity() / -180);
    gsap.to(".tarjeta", { skewY: skew, duration: 0.4, ease: "power3.out" });
  },
});

labelToScroll es la pieza que convierte una timeline con scrub en algo navegable: si tu timeline tiene etiquetas, puedes construir un índice cuyos enlaces lleven a la posición exacta de scroll que corresponde a cada capítulo.

const tl = gsap.timeline({
  scrollTrigger: { trigger: ".historia", start: "top top", end: "+=4000", scrub: 1, pin: true },
});
tl.addLabel("origen").to(".a", { xPercent: -100 })
  .addLabel("crisis").to(".b", { xPercent: -100 })
  .addLabel("cierre").to(".c", { xPercent: -100 });

document.querySelector("#ir-a-crisis").addEventListener("click", () => {
  window.scrollTo({ top: tl.scrollTrigger.labelToScroll("crisis"), behavior: "smooth" });
});

Fíjate en que la instancia es accesible desde la animación con tl.scrollTrigger. Es la vía inversa a self.animation y evita tener que guardar referencias en variables sueltas.

Los callbacks del ciclo de vida

Además de los de posición hay tres que hablan del sistema, no del scroll.

onRefresh se dispara cuando la instancia recalcula sus posiciones, que es donde debes poner cualquier medida propia que dependa del layout. Todo lo que calcules en el cuerpo del módulo se calcula una vez y se queda obsoleto en el primer resize; lo que calcules en onRefresh se recalcula con el resto.

onScrubComplete se dispara cuando un scrub numérico termina de alcanzar su objetivo, y solo existe si el scrub es un número. onSnapComplete se dispara al terminar un ajuste por snap, y no se dispara si el usuario interrumpe el ajuste tocando el scroll.

let anchoCarril = 0;

ScrollTrigger.create({
  trigger: ".carril",
  start: "top top",
  end: () => "+=" + anchoCarril,
  onRefresh: () => {
    anchoCarril = document.querySelector(".carril").scrollWidth - window.innerWidth;
  },
});

Y a nivel global existe ScrollTrigger.addEventListener(), que escucha sucesos que no pertenecen a ninguna instancia concreta: "scrollStart", "scrollEnd", "refreshInit", "refresh", "revert" y "matchMedia". "refreshInit" es especialmente útil, porque se dispara antes de que nada se mida, que es el único momento seguro para deshacer transformaciones que falsearían la medición.

Cuándo el callback correcto es ninguno

Merece la pena decirlo explícitamente porque es la causa más común de páginas que se atascan: onUpdate se ejecuta en cada frame durante el scroll, y todo lo que metas ahí se paga sesenta veces por segundo, en el hilo principal, mientras el usuario está haciendo la única acción en la que el jank se nota inmediatamente.

Escribir element.style.transform en onUpdate está bien. Leer getBoundingClientRect() en onUpdate fuerza un recálculo de layout en cada frame. Modificar innerHTML es peor todavía. Y crear un tween nuevo en cada onUpdate es catastrófico: acabas con cientos de tweens compitiendo por la misma propiedad.

Cuando la reacción es una animación, casi siempre la respuesta correcta no es un callback sino un segundo ScrollTrigger con scrub, que hace lo mismo con código optimizado y sin que tú toques el hilo principal. Y cuando de verdad necesitas un cálculo por frame, gsap.quickTo() te da un setter reutilizable que evita crear un tween nuevo cada vez.

// En lugar de un gsap.to dentro de onUpdate
const setSkew = gsap.quickTo(".tarjeta", "skewY", { duration: 0.4, ease: "power3.out" });

ScrollTrigger.create({
  trigger: ".seccion",
  start: "top bottom",
  end: "bottom top",
  onUpdate: (self) => setSkew(gsap.utils.clamp(-12, 12, self.getVelocity() / -180)),
});