Integrating GSAP with Vue 3 for Stunning Scroll Animations

Creating memorable web experiences often relies on the subtle art of animation. While CSS transitions are great for simple hover states, the GreenSock Animation Platform (GSAP) is the undisputed king of complex, timeline-based, and scroll-driven animations.

When paired with Vue 3's Composition API, GSAP becomes incredibly powerful. Here's a comprehensive guide to mastering this combination.

Why GSAP?

GSAP offers unmatched performance, cross-browser consistency, and an incredibly intuitive API. Its ScrollTrigger plugin allows you to trigger animations precisely as elements enter or leave the viewport, pin elements, or scrub animations based on scroll position.

Setup in Nuxt/Vue 3

First, install the library:

npm install gsap

To avoid SSR issues in Nuxt, we often register the plugin globally on the client side, or specifically within our components.

import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

The Vue 3 Approach: onMounted and onUnmounted

Because GSAP manipulates the DOM directly, we must wait until the component is fully mounted. In Vue 3, we use the onMounted lifecycle hook. Crucially, to prevent memory leaks, especially with ScrollTrigger, we must clean up in onUnmounted.

<template>
  <div class="box-container">
    <div ref="boxRef" class="box">Animate Me</div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { gsap } from 'gsap'

const boxRef = ref(null)
let ctx;

onMounted(() => {
  // Use gsap.context to easily clean up all animations created within it
  ctx = gsap.context(() => {
    gsap.to(boxRef.value, {
      x: 200,
      rotation: 360,
      duration: 2,
      ease: 'power3.out'
    });
  });
})

onUnmounted(() => {
  ctx.revert(); // This cleans up all GSAP animations and ScrollTriggers!
})
</script>

Mastering ScrollTrigger

ScrollTrigger is where the magic happens. Let's create an animation that fires when an element enters the screen.

gsap.from('.stagger-item', {
  scrollTrigger: {
    trigger: '.stagger-container',
    start: 'top 80%', // When the top of the container hits 80% down the viewport
    end: 'bottom 20%',
    toggleActions: 'play none none reverse', // play on enter, reverse on leave back
  },
  y: 50,
  opacity: 0,
  duration: 0.8,
  stagger: 0.2
})

Pro Tip: gsap.context() is your Best Friend

In modern Vue/React development, cleaning up ScrollTrigger instances used to be tedious. The introduction of gsap.context() solves this. Any animation or ScrollTrigger created inside a context can be instantly killed by calling .revert() on that context when the component unmounts.

Conclusion

GSAP and Vue 3 are a match made in heaven for creative developers. By understanding the lifecycle hooks and utilizing gsap.context(), you can build incredibly complex, high-performance animations that are completely free of memory leaks.