El mapa del ecosistema de plugins

GSAP no es una librería: es un núcleo pequeño más una veintena de plugins que resuelven problemas muy distintos entre sí. Esa arquitectura es deliberada —el núcleo se mantiene ligero y solo pagas por lo que cargas— pero tiene un efecto secundario: quien llega nuevo no sabe qué hay disponible y acaba resolviendo a mano cosas que un plugin hace en dos líneas. Este es el mapa completo, agrupado por el tipo de problema que resuelve cada pieza, para que la próxima vez que te encuentres un encargo sepas si ya está resuelto.

Lo que ya está en el núcleo

Antes del mapa, lo que no hace falta cargar. El paquete gsap incluye de serie el motor de tweens y timelines, el sistema de eases básicos, gsap.utils, y varios plugins internos que no hay que registrar:

• CSSPlugin se encarga de todo lo relacionado con propiedades CSS, incluidos los atajos de transformación (x, y, xPercent, rotation, scale, skew), autoAlpha, la interpolación de cadenas complejas como sombras, las variables personalizadas y clearProps.
• AttrPlugin anima atributos de elementos que no son propiedades CSS, con la sintaxis attr: { ... }. Es lo que necesitas para animar viewBox, r, cx o cualquier atributo numérico de SVG.
• SnapPlugin redondea valores durante la animación con la sintaxis snap: { ... }.
• DirectionalRotationPlugin está integrado en CSSPlugin: los sufijos _cw, _ccw y _short en las rotaciones funcionan sin cargar nada.
• ModifiersPlugin permite interceptar cada valor antes de aplicarlo con la sintaxis modifiers: { ... }, que es la base de los carruseles infinitos.

Un porcentaje sorprendente de las preguntas de principiante se responden con “eso ya está en el núcleo”.

Las familias de plugins

Scroll

Tres plugins, y la confusión entre ellos es la más habitual.

ScrollTrigger es el fundamental. Asocia una animación —o simplemente unas llamadas— a la posición del scroll: dispara al entrar, sincroniza el progreso con el desplazamiento, fija elementos mientras se recorren, y expone el ciclo de vida completo con marcadores visuales para depurar. Es la pieza más grande y la más usada del ecosistema.

ScrollSmoother sustituye el scroll nativo por uno interpolado y añade efectos de profundidad por capas. Depende de ScrollTrigger. Es también el plugin más discutible del conjunto: rompe el scroll nativo, y con él las expectativas del usuario, el comportamiento del teclado y la aceleración de la plataforma. Úsalo cuando el encargo lo pida explícitamente y sabiendo lo que cuesta.

ScrollToPlugin hace lo contrario: anima la posición del scroll hacia un destino. Es la pieza para un “volver arriba” con easing o para navegar a una sección. No confundas ScrollTo con ScrollTrigger: uno mueve el scroll, el otro escucha el scroll.

SVG

MorphSVG interpola entre dos formas SVG cualesquiera, resolviendo por su cuenta el problema difícil: emparejar puntos entre trazados con distinto número de nodos y elegir el punto de partida que produce la deformación más corta. Hacerlo a mano es un proyecto en sí mismo.

DrawSVG anima el dibujado progresivo de un trazo. Internamente maneja stroke-dasharray y stroke-dashoffset calculando las longitudes por ti, y admite dibujar desde cualquier porcentaje a cualquier otro, no solo de cero a cien.

MotionPath mueve cualquier elemento —del DOM o de SVG— a lo largo de un trazado, con alineación automática a la tangente. Es el equivalente programático de lo que hace offset-path en CSS, con la diferencia de que acepta un array de puntos arbitrarios y los convierte en una curva suave, y de que puede alinear un elemento HTML con un trazado SVG resolviendo la conversión entre sistemas de coordenadas.

MotionPathHelper es una herramienta de edición: inyecta en la página un editor visual de la trayectoria que puedes arrastrar y del que copias el resultado. No va a producción.

Interfaz e interacción

Draggable convierte cualquier elemento en arrastrable, con soporte de puntero y táctil, límites, ejes restringidos, rotación y ajuste a incrementos. Combinado con InertiaPlugin añade el desplazamiento con inercia al soltar, que es lo que hace que un carrusel arrastrable se sienta nativo.

Observer es la abstracción de gestos unificada: normaliza rueda, arrastre táctil, arrastre de puntero y teclas de dirección en un único conjunto de callbacks con dirección y velocidad. Es la pieza correcta para un scroll por secciones con gestos, y muchísimo menos código que escuchar cinco eventos distintos.

Flip resuelve la animación entre dos estados de layout que no son interpolables: un elemento que cambia de contenedor, una rejilla que se reordena, una tarjeta que pasa a pantalla completa. Captura el estado inicial, deja que el DOM cambie, y anima la diferencia con transformaciones. Es el patrón FLIP clásico con toda la contabilidad resuelta.

GSDevTools añade un panel flotante con línea de tiempo, barra de progreso y control de velocidad sobre cualquier animación. Es una herramienta de desarrollo que no debe quedarse en el bundle de producción.

Texto

SplitText divide un bloque de texto en caracteres, palabras o líneas envueltos en elementos individuales, para poder animarlos por separado. La parte difícil que resuelve son las líneas: dónde rompe el texto depende del ancho, de la fuente cargada y del idioma, así que requiere volver a dividir cuando cualquiera de esas cosas cambia.

ScrambleTextPlugin produce el efecto de texto que se descifra carácter a carácter, con control del juego de caracteres y de la velocidad de revelado.

TextPlugin sustituye el contenido de texto de un elemento carácter a carácter, como una máquina de escribir. Es el más simple de los tres y el que la gente suele buscar cuando encuentra los otros dos.

Física y eases

Physics2D anima con velocidad, ángulo, aceleración y gravedad en dos dimensiones: es lo que quieres para confeti, partículas o cualquier cosa que salga despedida. PhysicsPropsPlugin hace lo mismo sobre propiedades individuales en lugar de sobre un vector.

CustomEase permite definir una curva de easing arbitraria a partir de datos de trazado SVG o de una cadena cubic-bezier. CustomBounce y CustomWiggle generan curvas paramétricas de rebote y de vibración. Los tres se cargan aparte del núcleo.

También fuera del núcleo, en un fichero llamado EasePack, viven tres eases: rough, slow y expoScale.

Los plugins de integración

PixiPlugin y EaselPlugin adaptan GSAP a las peculiaridades de esas dos bibliotecas de canvas, principalmente en el tratamiento del color y de las transformaciones. Si no usas Pixi ni EaselJS, no existen para ti.

CSSRulePlugin anima propiedades de una regla CSS entera en vez de un elemento, incluidos pseudoelementos. Es el que la gente busca para animar un ::before, y hay que decir lo siguiente: hoy casi siempre es mejor idea declarar una variable personalizada en el elemento, usarla desde el pseudoelemento y animar la variable, porque eso funciona con el modelo de cascada normal y no manipula la hoja de estilos.

// Preferible a CSSRulePlugin para animar un pseudoelemento.
gsap.to('.tarjeta', { '--brillo': '1', duration: 0.6 });

.tarjeta { --brillo: 0; }
.tarjeta::before { opacity: var(--brillo); }