GSAP's advanced staggers allow you to define a grid which assumes that everything in the array is uniformly spaced. But what if there are gaps, different quantities in each row, etc. like in the example above? Perhaps it doesn't even resemble a grid at all. Notice the staggering still flows nicely in this demo thanks to a distributeByPositions() helper function.

How does it work?

In the JS panel, you'll find a distributeByPosition() method that you can copy into your project. Then, simply wrap it around your config object that you would normally use for an advanced stagger, and it'll spit back a function that's understood by GSAP's advanced stagger feature. Staggers will be distributed based on the x/y positions of the DOM elements using getBoundingClientRect() internally. The elements could be anywhere on the screen and it'll measure the distances and stagger things accordingly.

Sample code:

gsap.to(".box", {
  duration: 1,
  scale: 0.1,
  y: 40,
  ease: "power1.inOut",
  stagger: distributeByPosition({
    from: "center",
    amount: 2
  })
});

Configuration

The config object may contain any of the following optional properties:

Why wasn't wasn't this baked into GSAP? Why is a helper function needed?

Primarily because of file size concerns. The grid feature seemed to cover the vast majority of use cases and GSAP was built to allow for these advanced functions to be leveraged externally if you need to accommodate an edge case like this.

If you need any help, post in our forums. Happy tweening!