Chapter 135: gsap.utils.distribute()

Core Idea

distribute() returns a function that assigns a value to each element based on its position in an array (or grid), which is the same mechanism GSAP's advanced staggers use internally.

Reference Tables

Config key	Description
base	starting value (default 0)
amount	total amount distributed across targets, added to base
from	starting position: index, "start"/"center"/"edges"/"random"/"end", or [x, y] ratios
grid	[rows, columns] to distribute by 2D position instead of a flat array
axis	for grid mode, which axis to base distribution on
ease	optional easing curve applied to the distribution

Code Examples

let distributor = gsap.utils.distribute({ base: 50, amount: 100, from: "center" });
gsap.to(".box", { y: distributor, stagger: 0.05 });

• What it demonstrates: building a distributor function and feeding it directly as a tween's property value so each box gets a different y based on its position relative to the center.

Key Takeaways

1. This is what powers GSAP's advanced (grid/position-aware) stagger configs — you can use it standalone for any numeric property, not just staggers.

Connects To

• Stagger patterns (Guide): higher-level stagger usage this powers.