React GSAP Animation Library

A comprehensive React animation library leveraging GSAP's official React integration (useGSAP) for optimal performance and developer experience. This library provides beautiful, performant animations with minimal setup and proper cleanup.

Features

• 🚀 Official GSAP React Integration - Uses @gsap/react for optimal performance
• ⚙️ Robust Animation Context - Global settings with accessibility features
• 📱 Context-Safe Event Handlers - Proper GSAP context association for event handlers
• 🔄 Scroll-Based Animations - Integrated with GSAP's ScrollTrigger
• 🐞 Clean Unmounting - Proper cleanup of animations on component unmount
• 🧩 Independent Components - Each component works without depending on others
• 🎛️ Central Configuration - Global animation settings through context
• 🌐 SSR Support - Proper functioning in server-side rendering environments

What's New in Version 2.0.0

This major update brings significant improvements:

• Integration with the official @gsap/react package
• Enhanced GSAP context management for proper cleanup
• Improved animation performance and code organization
• Better accessibility support including reduced motion preferences
• Simplified API with more powerful features
• New components like TypingText for typewriter effects

Installation

npm install react-gsap-animation-library gsap @gsap/react
# or
yarn add react-gsap-animation-library gsap @gsap/react

Quick Start

import React from 'react';
import { 
  AnimationProvider, 
  FadeIn, 
  SlideIn, 
  TextReveal,
  TypingText,
  AnimatedButton 
} from 'react-gsap-animation-library';

function App() {
  return (
    <AnimationProvider>
      <div className="app">
        <FadeIn duration={1} delay={0.2} direction="up">
          <h1>Hello Animation World!</h1>
        </FadeIn>
        
        <SlideIn direction="right" distance={100} bounce={true}>
          <p>This text slides in from the right with a bounce effect</p>
        </SlideIn>
        
        <TextReveal 
          direction="left" 
          backgroundColor="#3498db" 
          maskStyle="gradient"
        >
          Revealing text with a mask effect
        </TextReveal>
        
        <TypingText 
          text={["Hello!", "Welcome to React GSAP Animation Library", "Try it now!"]} 
          typingSpeed={15}
          loop={Infinity}
        />
        
        <AnimatedButton effect="ripple" effectColor="rgba(255, 255, 255, 0.5)">
          Click Me!
        </AnimatedButton>
      </div>
    </AnimationProvider>
  );
}

Global Animation Settings

The library provides a context provider for global animation settings:

import { AnimationProvider, useAnimationSettings } from 'react-gsap-animation-library';

function App() {
  return (
    <AnimationProvider settings={{
      defaultDuration: 0.8,        // Default animation duration
      defaultEase: 'power3.out',   // Default easing function
      disableScrollAnimations: false,  // Disable all scroll-triggered animations
      disableAllAnimations: false,     // Disable all animations
      respectReducedMotion: true,      // Respect prefers-reduced-motion setting
      lowPowerMode: false              // Reduce animation complexity for battery savings
    }}>
      <YourApp />
    </AnimationProvider>
  );
}

// Access settings in any component
function MyComponent() {
  const { 
    disableAllAnimations,
    defaultDuration,
    updateSettings
  } = useAnimationSettings();
  
  // You can update settings programmatically
  const disableAnimations = () => {
    updateSettings({ disableAllAnimations: true });
  };
  
  return (
    <div>
      <button onClick={disableAnimations}>Disable Animations</button>
    </div>
  );
}

Core Components

FadeIn

Fade in elements with optional directional movement.

<FadeIn 
  direction="up"        // 'up', 'down', 'left', 'right', 'none'
  duration={0.8}        // Animation duration in seconds
  delay={0.2}           // Delay before animation starts
  distance={30}         // Movement distance in pixels
  ease="power3.out"     // GSAP easing function
  trigger="load"        // 'load', 'scroll', 'none' (manual control)
  threshold={0.1}       // Viewport threshold for scroll animations
  stagger={0.1}         // Stagger delay for child elements
  onComplete={() => {}} // Callback when animation completes
>
  <div>Content to animate</div>
</FadeIn>

SlideIn

Slide elements into view with optional bounce effect.

<SlideIn 
  direction="left"       // 'up', 'down', 'left', 'right'
  duration={0.8}         // Animation duration in seconds
  delay={0}              // Delay before animation starts
  distance={100}         // Movement distance in pixels
  ease="power2.out"      // GSAP easing function
  bounce={true}          // Add bounce effect
  bounceIntensity={0.3}  // Strength of bounce (0-1)
  trigger="scroll"       // 'load', 'scroll', 'none' (manual control)
  threshold={0.2}        // Viewport threshold for scroll animations
>
  <div>Sliding content</div>
</SlideIn>

TextReveal

Reveal text with a mask effect.

<TextReveal 
  direction="left"          // 'left', 'right', 'top', 'bottom'
  duration={1.2}            // Animation duration in seconds
  delay={0.1}               // Delay before animation starts
  ease="power4.inOut"       // GSAP easing function
  backgroundColor="#3498db" // Mask color
  textColor="#ffffff"       // Text color
  maskStyle="solid"         // 'solid', 'gradient', 'split'
  trigger="scroll"          // 'load', 'scroll', 'none' (manual control)
  threshold={0.3}           // Viewport threshold for scroll animations
>
  Text to reveal with mask effect
</TextReveal>

TypingText

Create typewriter-like text animations.

<TypingText 
  text="Single text to type"  // String or array of strings to type
  // text={["First text", "Second text"]}  // Multiple texts
  typingSpeed={10}            // Characters per second
  deleteSpeed={5}             // Delete speed (for multiple texts)
  delayBetweenTexts={1.5}     // Delay between different texts
  startDelay={0.5}            // Initial delay before typing starts
  cursorBlink={true}          // Enable cursor blinking
  cursorChar="|"              // Character to use as cursor
  cursorColor="inherit"       // Cursor color
  trigger="load"              // 'load', 'scroll', 'none' (manual control)
  loop={0}                    // Number of loops (0 = no loop, Infinity = infinite)
/>

AnimatedButton

Enhanced button with hover and click animations.

<AnimatedButton 
  effect="scale"              // 'scale', 'ripple', 'glow', 'magnetic'
  duration={0.3}              // Animation duration
  effectColor="rgba(255,255,255,0.5)" // Effect color for ripple/glow
  hoverScale={1.05}           // Scale on hover
  clickScale={0.95}           // Scale on click
  ease="power2.out"           // Easing function
  className="custom-button"   // Additional class names
  style={{}}                  // Custom inline styles
  onClick={() => {}}          // Click handler
>
  Click Me!
</AnimatedButton>

Custom Hooks

useAnimation

Create GSAP animations with proper context handling:

import { useAnimation } from 'react-gsap-animation-library';

function MyComponent() {
  const elementRef = useRef(null);
  
  // Create a GSAP animation with proper context
  const { tween, timeline, add, contextSafe } = useAnimation();
  
  useEffect(() => {
    // Create a tween - automatically cleaned up on unmount
    tween(elementRef.current, {
      x: 100,
      duration: 1,
      ease: 'power2.out'
    });
    
    // Or create a timeline
    const tl = timeline();
    tl.to(elementRef.current, { x: 100, duration: 1 })
      .to(elementRef.current, { y: 50, duration: 0.5 });
    
    // Make event handlers context-safe
    const onHover = contextSafe(() => {
      tween(elementRef.current, { scale: 1.2, duration: 0.3 });
    });
    
    elementRef.current.addEventListener('mouseenter', onHover);
    
    // Event listeners using contextSafe are automatically cleaned up
  }, []);
  
  return <div ref={elementRef}>Animated element</div>;
}

useAnimationEffect

Simplified API for common effects:

import { useAnimationEffect } from 'react-gsap-animation-library';

function MyComponent() {
  const elementRef = useRef(null);
  
  // Apply a predefined animation effect
  useAnimationEffect(elementRef, {
    effect: 'fadeIn',     // 'fadeIn', 'fadeOut', 'slideIn', etc.
    direction: 'up',      // Direction for effects that support it
    duration: 0.8,        // Duration in seconds
    delay: 0.2,           // Delay in seconds
    trigger: 'scroll',    // 'load', 'scroll', 'none'
    threshold: 0.2        // Viewport threshold for scroll
  });
  
  return <div ref={elementRef}>Element with effects</div>;
}

useScrollTrigger

Create scroll-based animations:

import { useScrollTrigger } from 'react-gsap-animation-library';

function MyScrollAnimation() {
  const elementRef = useRef(null);
  
  // Create a ScrollTrigger animation
  useScrollTrigger(elementRef, {
    animation: (target) => ({
      opacity: 1,
      y: 0,
      duration: 1
    }),
    initial: { opacity: 0, y: 50 },   // Initial state
    scrub: true,                      // Animate with scroll position
    start: 'top 80%',                 // ScrollTrigger start position
    end: 'bottom 20%',                // ScrollTrigger end position
    markers: false,                   // Show markers (debug)
    pin: false,                       // Pin element during animation
    toggleActions: 'play none none reverse'  // ScrollTrigger toggle actions
  });
  
  return <div ref={elementRef}>Scroll-animated content</div>;
}

Advanced Usage

Staggered Animations

import { FadeIn } from 'react-gsap-animation-library';

function StaggeredItems() {
  return (
    <FadeIn 
      stagger={0.1} 
      childClassName="stagger-item"
      direction="up"
      distance={20}
    >
      <div className="stagger-item">Item 1</div>
      <div className="stagger-item">Item 2</div>
      <div className="stagger-item">Item 3</div>
      <div className="stagger-item">Item 4</div>
    </FadeIn>
  );
}

Combined Animations

import { useAnimation } from 'react-gsap-animation-library';

function CombinedEffects() {
  const containerRef = useRef(null);
  const { timeline } = useAnimation();
  
  useEffect(() => {
    const tl = timeline();
    
    tl.from(containerRef.current, { opacity: 0, duration: 1 })
      .from('.title', { y: 50, opacity: 0, duration: 0.5 }, '-=0.5')
      .from('.content', { scale: 0.9, opacity: 0, duration: 0.5 }, '-=0.3')
      .from('.button', { y: 20, opacity: 0, duration: 0.3 }, '-=0.2');
  }, []);
  
  return (
    <div ref={containerRef}>
      <h1 className="title">Combined Animations</h1>
      <p className="content">Content with sequential animation</p>
      <button className="button">Animated Button</button>
    </div>
  );
}

Browser Support

• Chrome 60+
• Firefox 54+
• Safari 10.1+
• Edge 15+
• iOS Safari 10.3+
• Android Browser 67+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.