oraculo-radiohead: Skill for Cursor

gsap.utils

When to Use This Skill

Apply when writing or reviewing code that uses gsap.utils for math, array/collection handling, unit parsing, or value mapping in animations (e.g. mapping scroll to a value, randomizing, snapping to a grid, or normalizing inputs).

Related skills: Use with gsap-core, gsap-timeline, and gsap-scrolltrigger when building animations; CustomEase and other easing utilities are in gsap-plugins.

Overview

gsap.utils provides pure helpers; no need to register. Use in tween vars (e.g. function-based values), in ScrollTrigger or Observer callbacks, or in any JS that drives GSAP. All are on gsap.utils (e.g. gsap.utils.clamp()).

Omitting the value: function form. Many utils accept the value to transform as the last argument. If you omit that argument, the util returns a function that accepts the value later. Use the function form when you need to clamp, map, normalize, or snap many values with the same config (e.g. in a mousemove handler or tween callback). Exception: random() — pass true as the last argument to get a reusable function (do not omit the value); see random().

// With value: returns the result
gsap.utils.clamp(0, 100, 150); // 100

// Without value: returns a function you call with the value later
let c = gsap.utils.clamp(0, 100);
c(150);  // 100
c(-10);  // 0

Clamping and Ranges

clamp(min, max, value?)

Constrains a value between min and max. Omit value to get a function: 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?)

Maps a value from one range to another. Use when converting scroll position, progress (0–1), or input range to an animation range. Omit value to get a function: mapRange(inMin, inMax, outMin, outMax)(value).