Skip to content
Augusta BhardwajSay hello

GSAP ScrollTrigger on Mobile: All my Mistakes.

· 6 min read

I spent a week making the first version of my portfolio responsive. I was happy with the desktop version. Then I opened it on my phone.

Here are all the ScrollTrigger problems I ran into and how I solved them.

The 100vh Trap

In mobile Safari, the address bar is part of 100vh. So if you scroll past the address bar, your full height element all of the sudden has space at the bottom.

/* Bad */
.hero { min-height: 100vh; }

/* Better */
.hero { min-height: 100dvh; } /* dynamic viewport height */

/* Best for JS */
const vh = window.innerHeight; /* actual visible height */

On anything below 1025px, I stopped using 100vh in any way for pins. Instead, I just let content grow automatically, and add a little padding to fill the viewport.

Invisible Content

My scroll-triggered reveals were set to start: "top 80%". This meant "start the reveal when the top edge of this element is 80% into the viewport." This works beautifully.

Unfortunately, on a phone in portrait, the viewport is much taller relative to the content width. So an element that was in full view at 80% on desktop was still 100% out of view on the phone.

// The fix: more aggressive trigger on portrait
const triggerStart = isPortrait ? "top 95%" : "top 80%";

ScrollTrigger.create({
  trigger: sectionRef,
  start: triggerStart,
  onEnter: () => gsap.to(sectionRef, { opacity: 1, y: 0 }),
});

Pins create gaps

Pins are amazing. In a ScrollTrigger pin, your content stays in one spot while you scroll past. That's exactly what you want, right? Well not on mobile. The ScrollTrigger calculation for scroll distance assumes it's working in a viewport of a fixed height. So it creates gaps where there shouldn't be any!

I removed all pins in anything below 1025px, and replaced scroll-triggered content sections with vertically stacked sections with extra padding.

if (w >= 1025) {
  ScrollTrigger.create({
    trigger: section,
    pin: true,
    start: "top top",
    end: "+=500",
  });
}
// Below 1025px: no pin, just fade-in on scroll

Portrait detection

"Mobile" isn't just a screen width. An iPad in landscape is 1024px. That's bigger than lots of laptops. But in portrait, it's 768px with a really tall viewport.

The question isn't "is this a mobile device?" It's "is the viewport taller than it is wide?"

const isPortrait = window.innerWidth < 1025 && window.innerHeight > window.innerWidth;

This detects phones, portrait tablets, and small laptop windows. This was the most significant change in the layout. Instead of grid layouts, it becomes horizontal project scrolling. Instead of horizontal side by side sections, it's vertical stacked sections.

Touch Events

ScrollTrigger is great. It works on scroll. But on mobile, you want native swipe gestures. You want to be able to add touch and tap events. There are all kinds of ways to deal with this.

The fix is to manually attach touch event listeners on its own, don't try to force ScrollTrigger to listen for touch events (it's not designed to do so).

Refresh On Orientation Change

When a user rotates their device, every ScrollTrigger calculation is wrong. The viewport dimensions, the distance to the pins, the positions of the triggers have all changed.

window.addEventListener("orientationchange", () => {
  setTimeout(() => ScrollTrigger.refresh(), 300);
});

There is a 300ms delay from when a device is rotated to when ScrollTrigger refreshes. The browser needs time to settle.