gsap.utils
Cuándo usar este skill
Aplica al escribir o revisar código que use gsap.utils para matemáticas, manejo de arrays/colecciones, análisis de unidades o mapeo de valores en animaciones (por ejemplo, mapear scroll a un valor, aleatorizar, ajustar a una cuadrícula o normalizar entradas).
Skills relacionados: Úsalo con gsap-core, gsap-timeline y gsap-scrolltrigger al construir animaciones; CustomEase y otras utilidades de easing están en gsap-plugins.
Resumen
gsap.utils proporciona ayudas puras; no es necesario registrarlas. Úsalas en variables de tween (ej. valores basados en funciones), en callbacks de ScrollTrigger u Observer, o en cualquier JS que controle GSAP. Todas están en gsap.utils (ej. gsap.utils.clamp()).
Omitiendo el valor: forma de función. Muchas utilidades aceptan el valor a transformar como el último argumento. Si omites ese argumento, la utilidad devuelve una función que acepta el valor más tarde. Usa la forma de función cuando necesites fijar (clamp), mapear, normalizar o ajustar (snap) muchos valores con la misma configuración (ej. en un manejador de mousemove o un callback de tween). Excepción: random() — pasa true como último argumento para obtener una función reutilizable (no omitas el valor); consulta random().
// Con valor: devuelve el resultado
gsap.utils.clamp(0, 100, 150); // 100
// Sin valor: devuelve una función que llamas con el valor más tarde
let c = gsap.utils.clamp(0, 100);
c(150); // 100
c(-10); // 0
Fijado (Clamping) y Rangos
clamp(min, max, value?)
Restringe un valor entre min y max. Omite value para obtener una función: clamp(min, max)(value).
gsap.utils.clamp(0, 100, 150); // 100
gsap.utils.clamp(0, 100, -10); // 0
let clampFn = gsap.utils.clamp(0, 100);
clampFn(150); // 100
mapRange(inMin, inMax, outMin, outMax, value?)
Mapea un valor de un rango a otro. Úsalo al convertir posición de scroll, progreso (0-1) o rango de entrada a un rango de animación. Omite value para obtener una función: mapRange(inMin, inMax, outMin, outMax)(value).
gsap.utils.mapRange(0, 100, 0, 500, 50); // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (progreso a grados)
let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50); // 250
normalize(min, max, value?)
Devuelve un valor normalizado a 0-1 para el rango dado. Inverso de mapRange cuando el rango de destino es 0-1. Omite value para obtener una función: normalize(min, max)(value).
gsap.utils.normalize(0, 100, 50); // 0.5
gsap.utils.normalize(100, 300, 200); // 0.5
let normFn = gsap.utils.normalize(0, 100);
normFn(50); // 0.5
interpolate(inicio, fin, progreso?)
Interpola entre dos valores en un progreso dado (0-1). Maneja números, colores y objetos con claves coincidentes. Omite progreso para obtener una función: interpolate(inicio, fin)(progreso).
gsap.utils.interpolate(0, 100, 0.5); // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // color intermedio
gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
let lerp = gsap.utils.interpolate(0, 100);
lerp(0.5); // 50
Aleatorización (Random) y Ajuste (Snap)
random(minimo, maximo[, incrementoSnap, devolverFuncion]) / random(array[, devolverFuncion])
Devuelve un número aleatorio en el rango minimo-maximo, o un elemento aleatorio de un array. El incrementoSnap opcional ajusta el resultado al múltiplo más cercano (ej. 5 → múltiplos de 5). Para obtener una función reutilizable, pasa true como último argumento (devolverFuncion); la función devuelta no toma argumentos y devuelve un nuevo valor aleatorio cada vez. Esta es la única utilidad que usa true para la forma de función en lugar de omitir el valor.
// valor inmediato: número en rango
gsap.utils.random(-100, 100); // ej. 42.7
gsap.utils.random(0, 500, 5); // 0-500, ajustado al 5 más cercano
// función reutilizable: pasa true como último argumento
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn(); // valor aleatorio en rango, ajustado a 10
randomFn(); // otro valor aleatorio
// array: elige un valor al azar
gsap.utils.random(["rojo", "azul", "verde"]); // "rojo", "azul" o "verde"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray(); // 0, 100 o 200
Forma de cadena en variables de tween: usa "random(-100, 100)", "random(-100, 100, 5)" o "random([0, 100, 200])"; GSAP lo evalúa por objetivo.
gsap.to(".caja", { x: "random(-100, 100, 5)", duration: 1 });
gsap.to(".elemento", { backgroundColor: "random([rojo, azul, verde])" });
snap(ajuste, valor?)
Ajusta un valor al múltiplo más cercano de ajuste, o al valor más cercano en un array de valores permitidos. Omite valor para obtener una función: snap(ajuste)(valor) (o snap(arrayAjuste)(valor)).
gsap.utils.snap(10, 23); // 20
gsap.utils.snap(0.25, 0.7); // 0.75
gsap.utils.snap([0, 100, 200], 150); // 100 o 200 (el más cercano en el array)
let snapFn = gsap.utils.snap(10);
snapFn(23); // 20
Úsalo en tweens para animaciones basadas en cuadrícula o pasos:
gsap.to(".x", { x: 200, snap: { x: 20 } });
shuffle(array)
Devuelve un nuevo array con los mismos elementos en orden aleatorio. Úsalo para aleatorizar el orden (ej. stagger desde "random" con una copia).
gsap.utils.shuffle([1, 2, 3, 4]); // ej. [3, 1, 4, 2]
distribute(config)
Devuelve una función que asigna un valor a cada objetivo según su posición en el array (o en una cuadrícula). Se usa internamente para staggers avanzados; úsalo siempre que necesites valores distribuidos en muchos elementos (ej. escala, opacidad, x, retardo). La función devuelta recibe (indice, objetivo, objetivos) — ya sea llámala manualmente o pasa el resultado directamente a un tween; GSAP la llamará por objetivo con índice, elemento y array.
Config (todo opcional):
| Propiedad | Tipo | Descripción |
|---|---|---|
base | Número | Valor inicial. Por defecto 0. |
amount | Número | Total a distribuir entre todos los objetivos (se suma a base). Ej. amount: 1 con 100 objetivos → 0.01 entre cada uno. Usa each para fijar un paso por objetivo. |
each | Número | Cantidad a añadir entre cada objetivo (se suma a base). Ej. each: 1 con 4 objetivos → 0, 1, 2, 3. Usa amount para dividir un total. |
from | Número | Cadena | Array | Dónde comienza la distribución: índice, o "start", "center", "edges", "random", "end", o proporciones como [0.25, 0.75]. Por defecto 0. |
grid | Cadena | Array | Usa posición de cuadrícula en lugar de índice plano: [filas, columnas] (ej. [5, 10]) o "auto" para detectar. Omítelo para array plano. |
axis | Cadena | Para cuadrícula: limita a un eje ("x" o "y"). |
ease | Ease | Distribuye valores a lo largo de una curva de easing (ej. "power1.inOut"). Por defecto "none". |
En un tween: pasa el resultado de distribute(config) como valor de la propiedad; GSAP llama a la función para cada objetivo con (indice, objetivo, objetivos).
// Escala: elementos del medio 0.5, bordes exteriores 3 (cantidad 2.5 distribuida desde el centro)
gsap.to(".clase", {
scale: gsap.utils.distribute({
base: 0.5,
amount: 2.5,
from: "center"
})
});
Uso manual: llama a la función devuelta con (indice, objetivo, objetivos) para obtener el valor para ese índice.
const distribuidor = gsap.utils.distribute({
base: 50,
amount: 100,
from: "center",
ease: "power1.inOut"
});
const objetivos = gsap.utils.toArray(".caja");
const valorParaIndice2 = distribuidor(2, objetivos[2], objetivos);
Consulta distribute() para más información.
Unidades y Análisis
getUnit(valor)
Devuelve la cadena de unidad de un valor (ej. "px", "%", "deg"). Úsalo al normalizar o convertir valores.
gsap.utils.getUnit("100px"); // "px"
gsap.utils.getUnit("50%"); // "%"
gsap.utils.getUnit(42); // "" (sin unidad)
unitize(valor, unidad)
Añade una unidad a un número, o devuelve el valor tal cual si ya tiene unidad. Úsalo al construir valores CSS o valores finales de tween.
gsap.utils.unitize(100, "px"); // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem" (sin cambios)
splitColor(color, devolverHSL?)
Convierte una cadena de color en un array: [rojo, verde, azul] (0-255), o [rojo, verde, azul, alfa] (4 elementos para RGBA cuando alfa está presente o es necesario). Pasa true como segundo argumento (devolverHSL) para obtener [tono, saturación, luminosidad] o [tono, saturación, luminosidad, alfa] (HSL/HSLA) en su lugar. Funciona con "rgb()", "rgba()", "hsl()", "hsla()", hexadecimal y nombres de colores (ej. "red"). Úsalo al animar componentes de color o construir gradientes. Consulta splitColor().
gsap.utils.splitColor("red"); // [255, 0, 0]
gsap.utils.splitColor("#6fb936"); // [111, 185, 54]
gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5] (4 elementos)
gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL: tono, saturación, luminosidad)
Arrays y Colecciones
selector(ambito)
Devuelve una función de selector con ámbito que encuentra elementos solo dentro del elemento (o ref) dado. Úsalo en componentes para que selectores como ".caja" coincidan solo con descendientes de ese componente, no con todo el documento. Acepta un elemento DOM o una ref (ej. ref de React; maneja .current).
const q = gsap.utils.selector(refContenedor);
q(".caja"); // array de elementos .caja dentro del contenedor
gsap.to(q(".circulo"), { x: 100 });
toArray(valor, ambito?)
Convierte un valor a un array: cadena de selector (con ámbito a elemento), NodeList, HTMLCollection, elemento único o array. Úsalo al pasar entradas mixtas a GSAP (ej. objetivos) y se necesita un array real.
gsap.utils.toArray(".elemento"); // array de elementos
gsap.utils.toArray(".elemento", contenedor); // con ámbito al contenedor
gsap.utils.toArray(listaNodos); // [ ... ] desde NodeList
pipe(...funciones)
Compone funciones: pipe(f1, f2, f3)(valor) devuelve f3(f2(f1(valor))). Úsalo al aplicar una cadena de transformaciones (ej. normalizar → mapRange → snap) en un tween o callback.
const fn = gsap.utils.pipe(
(v) => gsap.utils.normalize(0, 100, v),
(v) => gsap.utils.snap(0.1, v)
);
fn(50); // normalizado y luego ajustado
wrap(min, max, valor?)
Envuelve un valor en el rango min-max (min inclusive, max exclusivo). Úsalo para scroll infinito o valores cíclicos. Omite valor para obtener una función: wrap(min, max)(valor).
gsap.utils.wrap(0, 360, 370); // 10
gsap.utils.wrap(0, 360, -10); // 350
let wrapFn = gsap.utils.wrap(0, 360);
wrapFn(370); // 10
wrapYoyo(min, max, valor?)
Envuelve el valor en un rango con efecto yoyo (rebota en los extremos). Úsalo para movimiento de ida y vuelta dentro de un rango. Omite valor para obtener una función: wrapYoyo(min, max)(valor).
gsap.utils.wrapYoyo(0, 100, 150); // 50 (rebota hacia atrás)
let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50
Mejores prácticas
- ✅ Omite el argumento de valor para obtener una función reutilizable cuando el mismo rango/config se use muchas veces (ej. manejador de scroll, callback de tween):
let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progreso). - ✅ Usa snap para valores alineados a cuadrícula o basados en pasos; usa toArray cuando GSAP o tu código necesite un array real a partir de un selector o NodeList.
- ✅ Usa gsap.utils.selector(ambito) en componentes para que los selectores tengan ámbito a un contenedor o ref.
No hacer
- ❌ Asumir que mapRange / normalize manejan unidades; trabajan con números. Usa getUnit / unitize cuando las unidades importen.
- ❌ Sobrescribir o confiar en comportamiento no documentado; cíñete a la API documentada.