Getting Familiar with GSAP ScrollTrigger 🌱

Is it just me, or does anyone else find GreenSock's ScrollTrigger documentation confusing? It took me some time to fully understand how each properties of ScrollTrigger work.
This article simplifies some common properties of ScrollTrigger, in case anyone has the same issue 🌱

Let's break down the following code one by one.

gsap.to(".element-to-animate", {
  scrollTrigger: {
    trigger: ".trigger-element",
    start: "top bottom",
    end: "bottom top",
    scrub: true,
    pin: true,
    toggleActions: "play none none none",
    toggleClass: "active",
    ease: "power2"
  }

Trigger

gsap.to(".element-to-animate", {
  scrollTrigger: {
    trigger: ".trigger-element",
  }

Breakdown

The position of .trigger-element will trigger the animation.

Start

start: "top bottom",

Breakdown

when the top of the .trigger-element reaches the bottom of the viewpoint, the animation will start.
In this case, this means it will start as soon as the element comes into view when you're scrolling down.

But for example, if we set it as

start: "top 90%",

The animation will start once 10% of the element becomes visible from the bottom of your screen.

End

end: "bottom top",

Breakdown

Similar to start, this means the animation will end once the target element's bottom reaches the top of the screen
In this case, this will be once the element becomes completely invisible from the screen.

Pin

pin: true

Breakdown

This one is pretty self-explanatory, it allows you to "pin" the .trigger-element.

Scrub

scrub: true

Breakdown

This allows smooth animation. So scrub: 1 means the animation will take 1 second to "catch up" to the scrollbar.

ToggleActions

toggleActions: "play none none none"

toggleActions sets how the animation will act during the following events - onEnter, onLeave, onEnterBack, and onLeaveBack, in that order. So

toggleActions: "play none none none"

is equivalent to

onEnter: "play",
onLeave: "none",
onEnterBack: "none",
onLeaveBack: "none"

Breakdown

The animation will 1. play when the target element comes into view, 2. do nothing when it leaves the view, 3. do nothing when it comes back into view, and 4. do nothing when it leaves the view again.

The possible options for these are:

• play
• pause
• resume
• reverse
• restart
• reset
• complete
• none

If you want your animation to restart every time the trigger element comes into view, you should opt for restart rather than play, as the following:

toggleActions: "restart none none none"

There is an awesome codepen demo by GreenSock for this, in case you want to see more options!

Ease

ease: "Power2"

Breakdown

Also self-explanatory, the animation's ease option.
There is a great visualizer by GreenSock for this here

ToggleClass

toggleClass: "active"

Breakdown

You can also add/remove classes with ScrollTrigger!
.active class will be added to the .element-to-animate while the ScrollTrigger is active, and removed otherwise. It is equivalent to document.querySelector('.element-to-animate').classList.add('.active') and document.querySelector('.element-to-animate').classList.remove('.active')

And That's It!

I hope this article will be helpful in case anyone else found ScrollTrigger's documentation confusing as I did.

Thanks for reading, and happy coding!