Gsap Utils

# 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()](https://gsap.com/docs/v3/GSAP/UtilityMethods/random()).

```javascript // 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)`.

```javascript 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)`.

```javascript gsap.utils.mapRange(0, 100, 0, 500, 50); // 250 gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (progress to degrees)

let mapFn = gsap.utils.mapRange(0, 100, 0, 500); mapFn(50); // 250 ```

### normalize(min, max, value?)

Returns a value normalized to 0–1 for the given range. Inverse of mapping when the target range is 0–1. Omit **value** to get a function: `normalize(min, max)(value)`.

```javascript 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(start, end, progress?)

Interpolates between two values at a given progress (0–1). Handles numbers, colors, and objects with matching keys. Omit **progress** to get a function: `interpolate(start, end)(progress)`.

```javascript gsap.utils.interpolate(0, 100, 0.5); // 50 gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color 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 ```

## Random and Snap

### random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])

Returns a random number in the range **minimum**–**maximum**, or a random element from an **array**. Optional **snapIncrement** snaps the result to the nearest multiple (e.g. `5` → multiples of 5). **To get a reusable function**, pass **true** as the last argument (**returnFunction**); the returned function takes no args and returns a new random value each time. This is the only util that uses `true` for the function form instead of omitting the value.

```javascript // immediate value: number in range gsap.utils.random(-100, 100); // e.g. 42.7 gsap.utils.random(0, 500, 5); // 0–500, snapped to nearest 5

// reusable function: pass true as last argument let randomFn = gsap.utils.random(-200, 500, 10, true); randomFn(); // random value in range, snapped to 10 randomFn(); // another random value

// array: pick one value at random gsap.utils.random(["red", "blue", "green"]); // "red", "blue", or "green" let randomFromArray = gsap.utils.random([0, 100, 200], true); randomFromArray(); // 0, 100, or 200 ```

**String form in tween vars:** use `"random(-100, 100)"`, `"random(-100, 100, 5)"`, or `"random([0, 100, 200])"`; GSAP evaluates it per target.

```javascript gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 }); gsap.to(".item", { backgroundColor: "random([red, blue, green])" }); ```

### snap(snapTo, value?)

Snaps a value to the nearest multiple of **snapTo**, or to the nearest value in an array of allowed values. Omit **value** to get a function: `snap(snapTo)(value)` (or `snap(snapArray)(value)`).

```javascript gsap.utils.snap(10, 23); // 20 gsap.utils.snap(0.25, 0.7); // 0.75 gsap.utils.snap([0, 100, 200], 150); // 100 or 200 (nearest in array)

let snapFn = gsap.utils.snap(10); snapFn(23); // 20