gsap-plugins

Plugins de GSAP

Cuándo Usar Este Skill

Aplica cuando uses o revises código que utiliza plugins de GSAP: registrar plugins, scroll-to, animaciones flip/FLIP, elementos arrastrables, SVG (DrawSVG, MorphSVG, MotionPath), texto (SplitText, ScrambleText), física, plugins de easing (CustomEase, EasePack, CustomWiggle, CustomBounce), o GSDevTools. ScrollTrigger tiene su propio skill (gsap-scrolltrigger).

Skills relacionados: Para tweens básicos usa gsap-core; para ScrollTrigger usa gsap-scrolltrigger; para React usa gsap-react.

Licencia e Instalación (importante)

Cada plugin de GSAP es gratuito, incluso para uso comercial. Desde la adquisición de GSAP por parte de Webflow, Club GSAP ya no es un nivel de pago y ningún plugin requiere membresía, clave de licencia o token de autenticación — esto incluye plugins que antes eran exclusivos de Club (SplitText, MorphSVG, etc.).

• ✅ Instala todo desde el paquete público gsap de npm: npm install gsap. Todos los plugins están incluidos — impórtalos como gsap/SplitText, gsap/MorphSVGPlugin, etc.
• ❌ No generes un archivo .npmrc con un token de autenticación de GreenSock, sugieras el registro privado npm.greensock.com, o le digas a los usuarios que se registren en Club GSAP para acceder a un plugin. Esas instrucciones están desactualizadas.

Registro de Plugins

Registra cada plugin una vez para que GSAP (y los empaquetadores) sepan que debe incluirlos. Usa gsap.registerPlugin() con cada plugin utilizado en el proyecto:

import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);

• ✅ Registra antes de usar el plugin en cualquier tween o llamada a la API.
• ✅ En React, registra a nivel superior o una vez en la aplicación (por ejemplo, antes del primer useGSAP); no registres dentro de un componente que se vuelva a renderizar. useGSAP es un plugin que debe registrarse antes de usarlo.

Scroll

ScrollToPlugin

Anima la posición de desplazamiento (ventana o elemento desplazable). Úsalo para "desplazar a un elemento" o "desplazar a una posición" sin ScrollTrigger.

gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });

ScrollToPlugin — configuración clave (objeto scrollTo):

Opción	Descripción
x, y	Posición de desplazamiento objetivo (número), o "max" para el máximo
element	Selector o elemento al que desplazarse (para desplazar a la vista)
offsetX, offsetY	Desplazamiento en píxeles desde la posición objetivo

ScrollSmoother

Contenedor de desplazamiento suave (suaviza el desplazamiento nativo). Requiere ScrollTrigger y una estructura DOM específica (contenedor de contenido + contenedor suave). Úsalo cuando se necesite un desplazamiento con estilo de momentum. Consulta la documentación de GSAP para la configuración; registra después de ScrollTrigger. La estructura DOM sería así:

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- TODO TU CONTENIDO AQUÍ --->
		</div>
	</div>
	<!-- los elementos con position: fixed pueden ir fuera --->
</body>

DOM / UI

Flip

Captura el estado con Flip.getState(), luego aplica cambios (por ejemplo, cambios de layout o clase), luego usa Flip.from() para animar desde el estado anterior al nuevo estado (FLIP: First, Last, Invert, Play). Úsalo cuando se anime entre dos estados de layout (listas, cuadrículas, expandido/contraído).

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// cambia el DOM (reordenar, añadir/eliminar, cambiar clases)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Flip — configuración clave (variables de Flip.from):

Opción	Descripción
absolute	Usa position: absolute durante el flip (por defecto: false)
nested	Cuando es true, solo se mide el primer nivel de hijos (mejor para transformaciones anidadas)
scale	Cuando es true, escala los elementos para que encajen (evita el estiramiento); por defecto true
simple	Cuando es true, solo se animan la posición/escala (más rápido, menos preciso)
duration, ease	Opciones estándar de tween

Más información

https://gsap.com/docs/v3/Plugins/Flip

Draggable

Hace que los elementos sean arrastrables, giratorios o lanzables con ratón/táctil. Úsalo para sliders, tarjetas, listas reordenables o cualquier interacción de arrastre.

gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });

Draggable — opciones clave de configuración:

Opción	Descripción
type	"x", "y", "x,y", "rotation", "scroll"
bounds	Elemento, selector o { minX, maxX, minY, maxY } para restringir el arrastre
inertia	true para habilitar lanzamiento/momentum (requiere InertiaPlugin)
edgeResistance	0–1; resistencia al arrastrar más allá de los límites
cursor	Cursor CSS durante el arrastre
onDragStart, onDrag, onDragEnd	Callbacks; reciben el evento y el objetivo
onThrowUpdate, onThrowComplete	Callbacks cuando la inercia está activa

Inertia (InertiaPlugin)

Funciona con Draggable para el momentum después de soltar, o rastrea la inercia/velocidad de cualquier propiedad de cualquier objeto para que luego pueda deslizarse suavemente hasta detenerse usando un tween simple. Regístrate con Draggable cuando uses inertia: true:

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });

O rastrea la velocidad de una propiedad:

InertiaPlugin.track(".box", "x");

Luego usa "auto" para continuar la velocidad actual y deslizarse hasta detenerse:

gsap.to(obj, { inertia: { x: "auto" } });

Observer

Normaliza la entrada de puntero y desplazamiento en todos los dispositivos. Úsalo para gestos de deslizamiento, dirección de desplazamiento o lógica de gestos personalizada sin vincularse directamente a la posición de desplazamiento como ScrollTrigger.

gsap.registerPlugin(Observer);

Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});

Observer — opciones clave de configuración:

Opción	Descripción
target	Elemento o selector a observar
onUp, onDown, onLeft, onRight	Callbacks cuando el deslizamiento/desplazamiento supera la tolerancia en esa dirección
tolerance	Píxeles antes de detectar la dirección; por defecto 10
type	"touch", "pointer" o "wheel" (por defecto: "touch,pointer")

Texto

SplitText

Divide el texto de un elemento en caracteres, palabras y/o líneas (cada uno en su propio elemento) para animación escalonada o por unidad. Úsalo cuando se anime texto carácter por carácter, palabra por palabra o línea por línea. Devuelve una instancia con chars, words, lines (y masks cuando se establece mask). Restaura el marcado original con revert() o deja que gsap.context() lo revierta. Se integra con gsap.context(), matchMedia() y useGSAP(). API: SplitText.create(target, vars) (target = selector, elemento o array).

gsap.registerPlugin(SplitText);

const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// más tarde: split.revert() o deja que gsap.context() lo revierta

Con onSplit() (v3.13.0+), las animaciones se ejecutan en cada división y en las redivisiones cuando se usa autoSplit; devolver un tween/timeline desde onSplit() permite que SplitText limpie y sincronice el progreso en la redivisión:

SplitText.create(".split", {
  type: "lines",
  autoSplit: true,
  onSplit(self) {
    return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
  }
});

SplitText — configuración clave (variables de SplitText.create):

Opción	Descripción
type	Separado por comas: "chars", "words", "lines". Por defecto "chars,words,lines". Divide solo lo necesario (por ejemplo, "words, chars" si no se usan líneas) para rendimiento. Evita chars solo sin words/lines o usa smartWrap: true para evitar saltos de línea extraños.
charsClass, wordsClass, linesClass	Clase CSS en cada elemento dividido. Añade "++" para agregar una clase incremental (por ejemplo, linesClass: "line++" → line1, line2, …).
aria	"auto" (por defecto), "hidden" o "none". Accesibilidad: "auto" añade aria-label en el elemento dividido y aria-hidden en los elementos de línea/palabra/carácter para que los lectores de pantalla lean la etiqueta; "hidden" oculta todo de los lectores; "none" deja aria sin cambios. Usa "none" más un duplicado solo para lectores de pantalla si los enlaces/semántica anidados deben exponerse.
autoSplit	Cuando es true, revierte y redividie cuando las fuentes terminan de cargar o cuando cambia el ancho del elemento (y las líneas están divididas), evitando saltos de línea incorrectos. Las animaciones deben crearse dentro de onSplit() para que apunten a los elementos recién divididos; return la animación desde onSplit() para limpieza automática y sincronización de tiempo en la redivisión.
onSplit(self)	Callback cuando se completa la división (y en cada redivisión si autoSplit es true). Recibe la instancia de SplitText. Devolver un tween o timeline de GSAP permite la reversión/sincronización automática de esa animación al redividir.
mask	"lines", "words" o "chars". Envuelve cada unidad en un elemento adicional con overflow: clip para efectos de máscara/revelado. Solo un tipo; accede a los wrappers en el array masks de la instancia (o usa la clase -mask si se establece una clase).
tag	Etiqueta del elemento envolvente; por defecto "div". Usa "span" para inline (nota: las transformaciones como rotación/escala pueden no renderizarse en elementos inline en algunos navegadores).
deepSlice	Cuando es true (por defecto), los elementos anidados (por ejemplo, <strong>) que abarcan varias líneas se subdividen para que las líneas no se estiren verticalmente. Solo se aplica al dividir líneas.
ignore	Selector o elemento(s) que se dejarán sin dividir (por ejemplo, ignore: "sup").
smartWrap	Al dividir solo chars, envuelve las palabras en un span con white-space: nowrap para evitar saltos de línea en medio de una palabra. Se ignora si se dividen palabras o líneas. Por defecto false.
wordDelimiter	Límite de palabra: string (por defecto " "), RegExp o { delimiter: RegExp, replaceWith: string } para división personalizada (por ejemplo, unión de ancho cero para hashtags o no latino).
prepareText(text, parent)	Función que recibe el texto sin procesar y el elemento padre; devuelve el texto modificado antes de dividir (por ejemplo, para insertar marcadores de salto en idiomas sin espacios).
propIndex	Cuando es true, añade una variable CSS con índice en cada elemento dividido (por ejemplo, --word: 1, --char: 2).
reduceWhiteSpace	Colapsa espacios consecutivos; por defecto true. Desde v3.13.0 también respeta saltos de línea y puede insertar <br> para <pre>.
onRevert	Callback cuando se revierte la instancia.

Consejos: Divide solo lo que se anima (por ejemplo, omite chars si solo se animan palabras). Para fuentes personalizadas, divide después de que carguen (por ejemplo, document.fonts.ready.then(...)) o usa autoSplit: true con onSplit(). Para evitar cambios de kerning al dividir chars, usa CSS font-kerning: none; text-rendering: optimizeSpeed;. Evita text-wrap: balance; puede interferir con la división. SplitText no soporta SVG <text>.

Más información: SplitText

ScrambleText

Anima el texto con un efecto de revuelto/glitch. Úsalo al revelar o hacer transiciones de texto con un revuelto.

gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});

SVG

DrawSVG (DrawSVGPlugin)

Revela u oculta el trazo de elementos SVG animando stroke-dashoffset / stroke-dasharray. Funciona en <path>, <line>, <polyline>, <polygon>, <rect>, <ellipse>. Úsalo al "dibujar" o "borrar" trazos.

Valor drawSVG: Describe el segmento visible del trazo a lo largo de la ruta (posiciones de inicio y fin), no "anima de A a B en el tiempo". Formato: "inicio fin" en porcentaje o longitud. Ejemplos: "0% 100%" = trazo completo; "20% 80%" = trazo solo entre el 20% y el 80% (huecos en ambos extremos). El tween anima desde el segmento actual del elemento hasta el segmento objetivo — por ejemplo, gsap.to("#path", { drawSVG: "0% 100%" }) va desde lo que sea ahora hasta el trazo completo. Un solo valor (por ejemplo, 0, "100%") significa que el inicio es 0: "100%" es equivalente a "0% 100%".

Requerido: El elemento debe tener un trazo visible — establece stroke y stroke-width en CSS o como atributos SVG; de lo contrario, no se dibuja nada.

gsap.registerPlugin(DrawSVGPlugin);

// dibuja desde nada hasta trazo completo
gsap.from("#path", { duration: 1, drawSVG: 0 });
// o segmento explícito: desde 0–0 hasta 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// trazo solo en el medio (huecos en los extremos)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });

Advertencias: Solo afecta el trazo (no el relleno). Prefiere elementos <path> de un solo segmento; las rutas de múltiples segmentos pueden renderizarse de manera extraña en algunos navegadores. El contenido de <use> no se puede cambiar visualmente. DrawSVGPlugin.getLength(element) y DrawSVGPlugin.getPosition(element) devuelven la longitud del trazo y la posición actual.

Más información: DrawSVG

MorphSVG (MorphSVGPlugin)

Transforma una forma SVG en otra animando el atributo d (datos de ruta). Las formas de inicio y fin no necesitan tener el mismo número de puntos — MorphSVG convierte a curvas cúbicas de Bézier y añade puntos según sea necesario. Úsalo para transformaciones de icono a icono, transiciones de forma o animaciones basadas en rutas. Funciona en <path>, <polyline> y <polygon>; <circle>, <rect>, <ellipse> y <line> se convierten internamente o mediante MorphSVGPlugin.convertToPath(selector | element) (reemplaza el elemento en el DOM con un <path>).

Valor morphSVG: Puede ser un selector (por ejemplo, "#lightning"), un elemento, datos de ruta sin procesar (por ejemplo, "M47.1,0.8 73.3,0.8..."), o para polygon/polyline una cadena de puntos (por ejemplo, "240,220 240,240..."). Puede ser un objeto con:

• shape – selector, elemento o datos de ruta sin procesar
• shapeIndex – número de forma (para rutas con múltiples formas); por defecto 0
• prepend – datos de ruta opcionales para anteponer (útil para iconos que se transforman en path/rect complejos)
• Si es un selector simple (cadena), se lee el atributo d del elemento.

Configuración clave (morphSVG en los vars de gsap.to / from):

Opción	Descripción
shapeIndex	Cuando la ruta de destino contiene múltiples formas (carga útil), este índice elige cuál debe aparecer; por defecto 0
useInlineStyles	Por defecto false (más rápido). Cuando es true, escribe inline styles en los elementos de la ruta para el renderizado de Safari/IE
type	"rotational" (por defecto), "linear", "uniform" – cómo se asignan los puntos. rotational trata de mantener el orden de puntos (mejor para formas similares); linear recorre el perímetro sin rotación; uniform distribuye puntos uniformemente

// Ejemplo básico – transforma de un elemento a otro
gsap.to("#lightning", { duration: 0.5, morphSVG: "#circle" });

// Con un objeto para shapeIndex
gsap.to("#shape", { duration: 0.5, morphSVG: { shape: "#target", shapeIndex: 2 } });

Advertencias: El atributo d (y por lo tanto el morphing) solo es compatible con , y . Otros elementos deben convertirse primero con MorphSVGPlugin.convertToPath(), que reemplaza el elemento en el DOM. Los fill/stroke no están animados — el morphing solo cubre la geometría. El relleno/trazo de origen también aparecerá inmediatamente si el elemento de origen está presente en la página. Es posible que dos formas no se superpongan idealmente; type: "linear" o "uniform" puede ayudar. A veces se necesita fill: transparent inicial. El morphing funciona mejor con formas que tienen la misma dirección general y orientación. La ruta debe ser una forma cerrada si necesitas que coincida un contorno.

Más información: MorphSVG

MotionPath (MotionPathPlugin)

Anima un elemento a lo largo de una ruta SVG (o define una ruta con objetos/coordenadas). Úsalo para mover elementos a lo largo de rutas curvas o definidas por el usuario.

gsap.registerPlugin(MotionPathPlugin);

gsap.to("#plane", {
  duration: 2,
  motionPath: {
    path: "#flightPath",
    align: "#flightPath",
    alignOrigin: [0.5, 0.5],
    autoRotate: true
  }
});

MotionPath — configuración clave del objeto path:

Opción	Descripción
path	Selector SVG o datos de ruta sin procesar ("M...") o array de puntos/objetos
align	Selector/elemento de ruta o true para autoalinear (ver alignOrigin)
alignOrigin	[x, y] normalizado (0–1) del origen de alineación en el objetivo; por defecto [0.5, 0.5]
autoRotate	Cuando es true, rota el objetivo para seguir la tangente de la ruta. También puede ser un número para compensar grados, o false
curviness	0–? Cuánto se curvan las rutas calculadas a partir de puntos; por defecto 1 (valores más altos = más curvatura)
start, end	Posición inicial/final normalizada (0–1) a lo largo de la ruta; útil para animaciones parciales o en bucle
resolution	Resolución de muestreo para curvas bezier (no suele ser necesario cambiar)
type	"cubic" (por defecto), "thru", "perpendicular", "soft" – cómo se conectan los puntos
useRadians	Cuando es true, la rotación usa radianes en lugar de grados (para motores de juegos/Babylon/Three)

Se puede animar a lo largo de una ruta usando solo datos de ruta (sin elemento de ruta en el DOM):

gsap.to(".dot", {
  motionPath: {
    path: [
      { x: 100, y: 100 },
      { x: 200, y: 150 },
      { x: 300, y: 100 }
    ]
  }
});

Más información: MotionPath

Física / Easing

CustomEase

Crea curvas de easing personalizadas dibujando una curva bezier cúbica, útil para efectos de balón, rebote personalizado, y otros no lineales. No es necesario registrarlo.

import { CustomEase } from "gsap/CustomEase";

CustomEase.create("custom", "M0,0 C0.25,0.46 0.45,0.94 1,1");
gsap.to(".box", { duration: 1, ease: "custom" });

API: CustomEase.create("nombre", "curva");. También hay un generador visual en https://gsap.com/docs/v3/Plugins/CustomEase/.

EasePack

Añade easings extra: "sine.inOut", "circ.inOut", "expo.inOut", "back.inOut", "bounce.inOut", "elastic.inOut", "rough", "slow", "steps", etc. Úsalos como cualquier ease (e.g., ease: "back.inOut(1.7)").

CustomWiggle

Crea un efecto de vibración/wiggle con una curva de easing personalizada (oscila como un resorte). Las vibraciones se pueden personalizar por amplitud, frecuencia, etc.

CustomWiggle.create("myWiggle", { wiggles: 6, type: "ease-out" });
gsap.to(".box", { duration: 1, ease: "myWiggle", x: 200 });

CustomBounce

Crea easings de rebote personalizados con control sobre la amplitud y la frecuencia de cada rebote.

CustomBounce.create("myBounce", { strength: 0.7, endAtEnd: true });
gsap.to(".box", { duration: 1, ease: "myBounce", y: 400 });

GSDevTools

Añade una interfaz visual para depurar animaciones (control de reproducción, ralentización, búsqueda). Se vincula a un tween/timeline:

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { duration: 1, x: 200 });
GSDevTools.create({ animation: tl });

Opciones:

Opción	Descripción
animation	Tween o timeline a depurar
container	Contenedor CSS (por defecto: se añade al DOM)
css	Ruta a CSS personalizado (rara vez se necesita)
id	ID para el elemento contenedor
initState	Estado inicial: "play", "pause", "rewind"
dock	"top", "right", "bottom", "left" (por defecto: "top")
loop	true para bucle continuo
minimal	true para UI minimalista
width	Ancho del panel (por defecto: "100%")
height	Alto del panel

Resumen de Registro de Plugins

Plugin	Importar desde	Registrar
ScrollToPlugin	gsap/ScrollToPlugin	gsap.registerPlugin(ScrollToPlugin)
ScrollSmoother	gsap/ScrollSmoother	gsap.registerPlugin(ScrollSmoother, ScrollTrigger)
Flip	gsap/Flip	gsap.registerPlugin(Flip)
Draggable	gsap/Draggable	gsap.registerPlugin(Draggable, InertiaPlugin)
InertiaPlugin	gsap/InertiaPlugin	gsap.registerPlugin(InertiaPlugin)
Observer	gsap/Observer	gsap.registerPlugin(Observer)
SplitText	gsap/SplitText	gsap.registerPlugin(SplitText)
ScrambleTextPlugin	gsap/ScrambleTextPlugin	gsap.registerPlugin(ScrambleTextPlugin)
DrawSVGPlugin	gsap/DrawSVGPlugin	gsap.registerPlugin(DrawSVGPlugin)
MorphSVGPlugin	gsap/MorphSVGPlugin	gsap.registerPlugin(MorphSVGPlugin)
MotionPathPlugin	gsap/MotionPathPlugin	gsap.registerPlugin(MotionPathPlugin)
CustomEase	gsap/CustomEase	No es necesario registrar CustomEase.create
EasePack	gsap/EasePack	No es necesario registrar
CustomWiggle	gsap/CustomWiggle	No es necesario registrar CustomWiggle.create
CustomBounce	gsap/CustomBounce	No es necesario registrar CustomBounce.create
GSDevTools	gsap/GSDevTools	gsap.registerPlugin(GSDevTools)

Temas Relacionados

• GSAP Core (gsap-core skill): Animaciones básicas, timeline, easing, stagger, callbacks
• ScrollTrigger (gsap-scrolltrigger skill): Animaciones basadas en scroll, pines, markers
• GSAP React (gsap-react skill): useGSAP hook, useRef, patrones de limpieza