Skip to main content

random

Get a random number within a range (optionally rounding to an increment you provide), or a random element in an array.

Choose one of the following method signatures - either get a random value immediately or set the the returnFunction parameter to true to get a reusable function that returns a random value according to the range (or array) originally provided each time you call it:

1) random(minimum, maximum[, snapIncrement, returnFunction])​

  1. minimum : Number - The minimum value
  2. maximum : Number - The maximum value
  3. snapIncrement : Number (optional) - A snapping increment. For example, a value of 5 means the random number would snap to the closest increment of 5
  4. returnFunction : Boolean (optional) - If true, a reusable function will be returned instead of a random value. This function can be called anytime to randomly choose a value from the range originally provided.

Returns: a random value between minimum and maximum, or if returnFunction is true, a reusable function that can be called anytime to get a value randomly chosen from the range originally provided

Example​

// get a random number between -100 and 100 (no snapping)
gsap.utils.random(-100, 100);

// a random number between 0 and 500 that's snapped to the closest increment of 5
gsap.utils.random(0, 500, 5);

// get a reusable function that will randomly choose a value between -200 and 500, snapping to an increment of 10
var random = gsap.utils.random(-200, 500, 10, true);

// now we can call it anytime:
console.log(random()); // random value between -200 and 500, snapping to the closest 10
console.log(random()); // another random value between -200 and 500, snapping to the closest 10

2) random(array[, returnFunction])​

  1. array : Array - An array of values to randomly choose from
  2. returnFunction : Boolean (optional) - If true, a reusable function will be returned instead of a random value. This function can be called anytime to randomly choose a value from the array originally provided.

Returns: a value randomly chosen from the array, or if returnFunction is true, a reusable function that can be called anytime to get a value randomly chosen from the array

Example​

// get a random value from an array of colors
gsap.utils.random(["red", "blue", "green"]); //"red", "blue", or "green"

// get a reusable function that will randomly choose a value from the array of colors
var random = gsap.utils.random([0, 100, 200], true);

// now we can call it anytime:
console.log(random()); // 0, 100, or 200 (randomly selected)
console.log(random()); // 0, 100, or 200 (randomly selected again)

3) random(minimum, maximum[, returnFunction])​

  1. minimum : Number - The minimum value
  2. maximum : Number - The maximum value
  3. returnFunction : Boolean (optional) - If true, a reusable function will be returned instead of a random value. This function can be called anytime to randomly choose a value from the range originally provided.

Returns: a random value between minimum and maximum, or if returnFunction is true, a reusable function that can be called anytime to get a value randomly chosen from the range originally provided

This is identical it method signature 1 except that it omits the snapIncrement for convenience.

Example​

// get a random number between 0 and 100 (no snapping)
gsap.utils.random(0, 100);

// get a reusable function that will randomly choose a value between -10 and 50
var random = gsap.utils.random(-10, 50, true);

// now we can call it anytime:
console.log(random()); // random value between -10 and 50
console.log(random()); // another random value between -10 and 50

Tip: combine reusable functions for powerful data transformations!​

You can pipe() several reusable functions together to perform multiple tasks on an incoming value, like clamping, mapping to another range, snapping, interpolating, and more. For example:

// get a clamping function that will always clamp to a range between 0 and 100
var colorizer = gsap.utils.pipe(
  // clamp between 0 and 100
  gsap.utils.clamp(0, 100),

  // normalize to a value between 0 and 1
  gsap.utils.normalize(0, 100),

  // then interpolate between red and blue
  gsap.utils.interpolate("red", "blue")
);

// now we feed one value in and it gets run through ALL those transformations!:
colorizer(25.874);

Video demo: combining utility methods​

String form​

Note that inside of tween vars you can also use a string form like "random(-100, 100)" for a range or like "random([red, blue, green])". For example:

gsap.to(".class", {
  x: "random([0, 100, 200, 500])", //randomly selects one of the values (0, 100, 200, or 500)
});

You can even have the random number rounded to the closest increment of any number! For example:

gsap.to(".class", {
  x: "random(-100, 100, 5)", //chooses a random number between -100 and 100 for each target, rounding to the closest 5!
});

Contents