GSAP-Zeitleistenanimation

GSAP & Timeline Animation

Use GSAP when a project already includes it or when a multi-element choreographed sequence, reversible timeline, or scrubbed scroll scene exceeds what CSS and basic WAAPI handle cleanly.

Core Timeline & Property Discipline

1. Prefer transform shorthands and autoAlpha:
   • Animate x, y, xPercent, yPercent, scale, rotation, and autoAlpha (opacity + automatic visibility: hidden when opacity reaches 0 so invisible elements never block clicks).
   • Register plugins (ScrollTrigger, Flip, useGSAP) once at module initialization with gsap.registerPlugin(...).
2. Timelines over fragile delay chains:
   • Coordinate multi-step sequences with gsap.timeline({ defaults: { duration: 0.5, ease: 'power2.out' } }) and position parameters ("<", ">" , "-=0.15", "<0.08", or named .addLabel('reveal')). Changing step 1's duration then shifts all downstream steps automatically.
3. Avoid .from() flash of unstyled content (FOUC) & re-trigger traps:
   • Calling gsap.from(el, { opacity: 0, y: 24 }) repeatedly on rapid user clicks captures the current mid-tween value as the destination state, leaving elements stuck semi-transparent!
   • For re-triggerable interactions, use .fromTo(el, { autoAlpha: 0, y: 24 }, { autoAlpha: 1, y: 0, overwrite: 'auto' }) or control a persistent timeline instance (tl.play() / tl.reverse()).

Scoped Cleanup & Responsive Accessibility (gsap.context & gsap.matchMedia)

Never leave loose global selector tweens (gsap.to('.card', ...)) that leak across component unmounts or affect unrelated DOM instances:

// Scope selectors to the component container and handle responsive + reduced-motion rules cleanly
const mm = gsap.matchMedia(containerEl);

mm.add(
  {
    isDesktop: '(min-width: 768px)',
    isMobile: '(max-width: 767px)',
    reduceMotion: '(prefers-reduced-motion: reduce)',
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions!;
    if (reduceMotion) {
      gsap.set('.stage-card', { autoAlpha: 1, y: 0, clearProps: 'transform' });
      return;
    }
    const tl = gsap.timeline({
      scrollTrigger: {
        trigger: containerEl,
        start: 'top 75%',
        end: 'bottom 25%',
        toggleActions: 'play none none reverse',
      },
    });
    tl.from('.stage-card', {
      y: isDesktop ? 32 : 16,
      autoAlpha: 0,
      stagger: 0.08,
      duration: 0.55,
      ease: 'power3.out',
    });
  },
);

// On component unmount / teardown:
mm.revert(); // Reverts all tweens, inline styles, and ScrollTriggers created inside!

ScrollTrigger Guardrails

• Never attach scrollTrigger to a child tween inside a timeline: A tween cannot be controlled by both a parent timeline's playhead and the scrollbar simultaneously. Attach scrollTrigger to the top-level gsap.timeline({ scrollTrigger: { ... } }).
• Refresh after layout shifts: Call ScrollTrigger.refresh() after async data loads, accordion expansions, image decodes, or webfont readiness so cached start/end scroll offsets stay accurate.