GSAP animations implementation for website

Implementing GSAP Animations on a Website

GSAP (GreenSock Animation Platform) is the industry standard for complex web animations. Unlike CSS animations, GSAP provides precise control over timelines, supports grouping and sequences, works stably in Safari, and correctly pauses/rewinds. A paid license is only required for plugins (ScrollTrigger, MorphSVG, etc.) — the basic GSAP 3 is free and sufficient for most tasks.

Installation and Basic Configuration

npm install gsap
# ScrollTrigger is included in the main package

For Next.js and React, it's important to ensure that GSAP is not executed on the server (SSR):

// lib/gsap.ts — centralized initialization
import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { ScrollToPlugin } from 'gsap/ScrollToPlugin'

if (typeof window !== 'undefined') {
  gsap.registerPlugin(ScrollTrigger, ScrollToPlugin)

  // Configure global settings
  gsap.config({
    nullTargetWarn: false, // do not warn about null elements
    trialWarn: false,
  })

  // Reset ScrollTrigger on resize (important for mobile)
  ScrollTrigger.config({
    ignoreMobileResize: true,
  })
}

export { gsap, ScrollTrigger }

Hero Animation on Page Load

// components/HeroSection.tsx
import { useEffect, useRef } from 'react'
import { gsap } from '../lib/gsap'

export function HeroSection() {
  const containerRef = useRef<HTMLDivElement>(null)
  const headlineRef = useRef<HTMLHeadingElement>(null)
  const sublineRef = useRef<HTMLParagraphElement>(null)
  const ctaRef = useRef<HTMLButtonElement>(null)
  const imageRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const ctx = gsap.context(() => {
      // Entrance timeline
      const tl = gsap.timeline({
        defaults: { ease: 'power3.out', duration: 0.8 },
      })

      tl
        .from(headlineRef.current, {
          y: 60,
          opacity: 0,
          duration: 1,
        })
        .from(
          sublineRef.current,
          { y: 40, opacity: 0 },
          '-=0.5' // overlap -0.5s
        )
        .from(
          ctaRef.current,
          { y: 20, opacity: 0, scale: 0.95 },
          '-=0.4'
        )
        .from(
          imageRef.current,
          {
            x: 80,
            opacity: 0,
            duration: 1.2,
            ease: 'power2.out',
          },
          '<-0.6' // relative to previous start
        )
    }, containerRef)

    return () => ctx.revert() // cleanup on unmount
  }, [])

  return (
    <div ref={containerRef} className="hero-container">
      <h1 ref={headlineRef}>Headline</h1>
      <p ref={sublineRef}>Subheading</p>
      <button ref={ctaRef}>Get Started</button>
      <div ref={imageRef} className="hero-image" />
    </div>
  )
}

gsap.context() is a required pattern for React: it scopes all GSAP targets to containerRef and correctly removes animations on ctx.revert() call.

ScrollTrigger: Animations on Scroll

// components/FeatureCards.tsx
import { useEffect, useRef } from 'react'
import { gsap, ScrollTrigger } from '../lib/gsap'

export function FeatureCards() {
  const sectionRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const ctx = gsap.context(() => {
      // Stagger animation of cards when entering viewport
      gsap.from('.feature-card', {
        y: 80,
        opacity: 0,
        duration: 0.7,
        stagger: 0.15,
        ease: 'power2.out',
        scrollTrigger: {
          trigger: sectionRef.current,
          start: 'top 75%',   // animation starts when section is 75% from top
          end: 'bottom 20%',
          toggleActions: 'play none none reverse',
          // play = forward on enter, reverse = backward on exit upward
        },
      })

      // Parallax for background image
      gsap.to('.section-bg', {
        yPercent: -30,
        ease: 'none',
        scrollTrigger: {
          trigger: sectionRef.current,
          start: 'top bottom',
          end: 'bottom top',
          scrub: true, // bind to scroll position
        },
      })
    }, sectionRef)

    return () => ctx.revert()
  }, [])

  return (
    <div ref={sectionRef} className="features-section">
      <div className="section-bg" />
      {[1, 2, 3].map(i => (
        <div key={i} className="feature-card">Card {i}</div>
      ))}
    </div>
  )
}

Horizontal Scroll with ScrollTrigger

A popular effect — a section with horizontal scrolling on vertical scroll:

// components/HorizontalScroll.tsx
import { useEffect, useRef } from 'react'
import { gsap, ScrollTrigger } from '../lib/gsap'

export function HorizontalScroll({ items }: { items: string[] }) {
  const containerRef = useRef<HTMLDivElement>(null)
  const trackRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const ctx = gsap.context(() => {
      const track = trackRef.current!
      const totalWidth = track.scrollWidth - track.offsetWidth

      gsap.to(track, {
        x: -totalWidth,
        ease: 'none',
        scrollTrigger: {
          trigger: containerRef.current,
          pin: true,           // pin the section
          scrub: 1,            // smoothness 1s
          start: 'top top',
          end: `+=${totalWidth}`, // scroll length = content width
          invalidateOnRefresh: true, // recalculate on resize
        },
      })
    }, containerRef)

    return () => ctx.revert()
  }, [])

  return (
    <div ref={containerRef} className="overflow-hidden">
      <div ref={trackRef} className="flex gap-8 w-max py-20">
        {items.map((item, i) => (
          <div key={i} className="w-[400px] h-[300px] flex-shrink-0 bg-gray-100 rounded-xl flex items-center justify-center">
            {item}
          </div>
        ))}
      </div>
    </div>
  )
}

Custom Easing Functions

GSAP supports CustomEase for unique acceleration curves:

import { CustomEase } from 'gsap/CustomEase'
gsap.registerPlugin(CustomEase)

// Create from cubic-bezier or SVG path
CustomEase.create('myBounce', 'M0,0 C0.14,0 0.242,0.438 0.272,0.561 0.313,0.728 0.354,0.963 0.362,1 0.37,0.985 0.414,0.873 0.455,0.811')

gsap.to('.element', {
  x: 300,
  ease: 'myBounce',
  duration: 1.2,
})

Cleanup on Navigation (Next.js App Router)

In Next.js 13+ with App Router, components mount/unmount on navigation. ScrollTrigger needs to be cleaned up properly:

// hooks/useGSAPScrollTrigger.ts
import { useEffect, useLayoutEffect } from 'react'
import { gsap, ScrollTrigger } from '../lib/gsap'

// useLayoutEffect for synchronous DOM measurement
export function useGSAPScrollTrigger(
  setup: (context: gsap.Context) => void,
  deps: any[] = []
) {
  const isomorphicEffect =
    typeof window !== 'undefined' ? useLayoutEffect : useEffect

  isomorphicEffect(() => {
    const ctx = gsap.context(setup)
    return () => {
      ctx.revert()
      // Explicit killAll is needed for fast navigation
      ScrollTrigger.getAll().forEach(t => t.kill())
    }
  }, deps)
}

Performance

Several rules for smooth 60fps:

• Animate only transform and opacity — they don't cause reflow
• Use will-change: transform only for active animations, remove after
• gsap.set() instead of CSS for initial states — GSAP optimizes batching
• ScrollTrigger.batch() for large numbers of similar elements instead of separate instances

// Optimized batch for large lists
ScrollTrigger.batch('.list-item', {
  onEnter: elements => {
    gsap.from(elements, {
      opacity: 0,
      y: 40,
      stagger: 0.1,
      duration: 0.6,
    })
  },
  start: 'top 85%',
})

Typical Timelines

Hero animation + 2–3 ScrollTrigger sections — 1–2 working days. Full set of animations for a landing page (horizontal scroll, pin sections, stagger lists, parallax) — 4–6 working days. Custom animations for complex interactive scenes — separate estimation after technical specification.