react-native-gsap

v2.5.32

Published

3 days ago

Advanced GSAP-like animation library for React Native with scroll animations

📦 React Native GSAP

A powerful animation library for React Native, inspired by GSAP (GreenSock Animation Platform). Create smooth, performant animations with a familiar and expressive API.

📚 Documentation

Visit the official documentation website for interactive examples and detailed guides:

https://react-native-gsap.netlify.app/

npm version license

📋 Table of Contents

📦 Installation

npm install react-native-gsap
# or
yarn add react-native-gsap

No additional setup required! The library works with React Native's Animated API out of the box.

🚀 Quick Start

Here's a simple example to get you started:

import React from "react";
import { TouchableOpacity, View, StyleSheet } from "react-native";
import GSAP, { useAnimatedRef } from "react-native-gsap";

const App = () => {
  const boxRef = useAnimatedRef();

  const animate = () => {
    GSAP.to(boxRef.current, 1, {
      x: 150,
      rotation: 360,
      scale: 1.5,
      opacity: 0.5,
      backgroundColor: "#e74c3c",
      ease: "power2.out",
    });
  };

  const reset = () => {
    GSAP.to(boxRef.current, 0.5, {
      x: 0,
      rotation: 0,
      scale: 1,
      opacity: 1,
      backgroundColor: "#3498db",
    });
  };

  return (
    <View style={styles.container}>
      <GSAP.View ref={boxRef} style={styles.box} />
      <View style={styles.buttonRow}>
        <TouchableOpacity style={styles.button} onPress={animate}>
          <Text style={styles.buttonText}>Animate</Text>
        </TouchableOpacity>
        <TouchableOpacity style={[styles.button, styles.resetButton]} onPress={reset}>
          <Text style={styles.buttonText}>Reset</Text>
        </TouchableOpacity>
      </View>
    </View>
  );
};

🎯 Core Concepts

Animation Properties

You can animate a wide range of properties:

| Category | Properties | |--------------|----------------------------------------------------------------------------| | Transform | x, y, rotation, scale, scaleX, scaleY, skewX, skewY | | Colors | backgroundColor, color, borderColor, shadowColor | | Dimensions | width, height, borderRadius, borderWidth | | Positioning | top, left, right, bottom, margin, padding | | Opacity | opacity | | Typography | fontSize, fontWeight, lineHeight, textAlign |

Animation Controls

| Property | Type | Description | |---------------|----------|------------------------------------------| | duration | number | Animation duration in seconds | | delay | number | Delay before animation starts | | repeat | number | Number of repetitions (-1 for infinite)| | repeatDelay | number | Delay between repetitions | | yoyo | boolean | Reverse animation on repeat | | ease | string | Easing function name | | onStart | function | Called when animation starts | | onComplete | function | Called when animation completes | | onUpdate | function | Called on each frame | | onRepeat | function | Called on each repeat |

🎬 Animation Methods

GSAP.to()

Animates an element to the specified values.

GSAP.to(ref.current, 1, {
  x: 100,
  y: -50,
  rotation: 360,
  scale: 1.5,
  opacity: 0.5,
  backgroundColor: "#e74c3c",
  delay: 0.5,
  repeat: 2,
  yoyo: true,
  ease: "elastic.out",
  onStart: () => console.log("Started"),
  onComplete: () => console.log("Completed"),
});

GSAP.from()

Animates an element from the specified values to its current state.

GSAP.from(boxRef.current, 1, {
  x: 100,
  y: -50,
  scale: 0.5,
  opacity: 0,
  rotation: 180,
  backgroundColor: "#e74c3c",
});

GSAP.fromTo()

Animates an element from one set of values to another.

GSAP.fromTo(
  boxRef.current,
  1.5,
  { x: 0, y: 0, scale: 1, rotation: 0, backgroundColor: "#3498db" },
  { x: 200, y: -100, scale: 2, rotation: 360, backgroundColor: "#e74c3c", borderRadius: 50 }
);

GSAP.set()

Instantly sets properties without animation.

GSAP.set(boxRef.current, {
  x: 50,
  y: 20,
  rotation: 45,
  scale: 1.2,
  backgroundColor: "#f39c12",
});

// Then animate from these values
GSAP.to(boxRef.current, 1, { x: 0, rotation: 0, scale: 1 });

⏱️ Timeline

Timelines let you sequence multiple animations with precise control over timing.

Basic Timeline

const playTimeline = () => {
  const tl = GSAP.timeline();

  tl.to(boxRef.current, 0.5, { x: 100, backgroundColor: "#f39c12" })
    .to(boxRef.current, 0.5, { y: 100, backgroundColor: "#e74c3c" })
    .to(boxRef.current, 0.5, { x: 0, backgroundColor: "#9b59b6" })
    .to(boxRef.current, 0.5, { y: 0, backgroundColor: "#2ecc71", rotation: 360 });

  tl.play();
};

Timeline Controls

const tl = GSAP.timeline();

tl.play();     // Start
tl.pause();    // Pause
tl.resume();   // Resume from pause
tl.reverse();  // Play backwards
tl.restart();  // Start from beginning
tl.kill();     // Stop and destroy

Timeline Position Parameters

| Parameter | Description | Example | |------------|--------------------------------|--------------------------------------| | "+=0.5" | 0.5s after previous ends | .to(target, 1, vars, "+=0.5") | | "-=0.3" | 0.3s before previous ends | .to(target, 1, vars, "-=0.3") | | "<" | Same time as previous | .to(target, 1, vars, "<") | | "2" | At exactly 2 seconds | .to(target, 1, vars, 2) |

Complex Timeline Example

const tl = GSAP.timeline({
  repeat: 2,
  yoyo: true,
  onStart: () => console.log("Timeline started"),
  onComplete: () => console.log("Timeline completed"),
});

tl.to(boxRef.current, 0.8, { x: 100, rotation: 180, scale: 1.3, ease: "power2.out" })
  .to(circleRef.current, 0.6, { scale: 1.5, opacity: 0.7 }, "-=0.4")
  .to(boxRef.current, 0.5, { y: 100, rotation: 270 }, "+=0.2")
  .to(circleRef.current, 0.5, { x: 50, rotation: 180 }, "<")
  .to(boxRef.current, 1, { x: 0, y: 0, rotation: 360, scale: 1 });

tl.play();

✨ Stagger Animations

Stagger animations allow you to animate multiple elements with a delay between each.

GSAP.stagger()

const items = [ref1.current, ref2.current, ref3.current];

const staggerAnim = GSAP.stagger(
  items,
  0.8,              // Duration per item
  {
    y: -100,
    scale: 1.5,
    rotation: 360,
    opacity: 0.7,
    backgroundColor: "#e74c3c",
    ease: "back.out",
  },
  0.15              // Delay between each item
);

staggerAnim.play();

GSAP.staggerFrom()

GSAP.staggerFrom(items, 1, {
  y: -150,
  scale: 0.2,
  opacity: 0,
  rotation: -180,
  backgroundColor: "#f39c12",
}, 0.15).play();

GSAP.staggerTo()

GSAP.staggerTo(items, 0.8, {
  y: 100,
  scale: 1.3,
  rotation: 180,
  opacity: 0.7,
  backgroundColor: "#2ecc71",
  ease: "elastic.out",
}, 0.2).play();

Stagger Controls

const anim = GSAP.stagger(items, 0.8, vars, 0.15);

anim.play();    // Start
anim.pause();   // Pause
anim.resume();  // Resume
anim.reverse(); // Play backwards
anim.restart(); // Start over
anim.kill();    // Stop and destroy

🪝 Hooks

useAnimatedRef()

Creates a ref for use with animated components.

import { useAnimatedRef } from "react-native-gsap";

const MyComponent = () => {
  const boxRef = useAnimatedRef();

  useEffect(() => {
    GSAP.to(boxRef.current, 1, { x: 100, rotation: 360 });
  }, []);

  return <GSAP.View ref={boxRef} style={styles.box} />;
};

useGSAPAnimation()

Automatically updates styles on every animation frame. Perfect for components that need to reflect animation state.

import { useGSAPAnimation } from "react-native-gsap";

const AutoUpdatingBox = () => {
  const { ref, style } = useGSAPAnimation();

  useEffect(() => {
    GSAP.to(ref.current, 2, {
      x: 200,
      rotation: 360,
      scale: 1.5,
      repeat: -1,
      yoyo: true,
    });
  }, []);

  return <GSAP.View ref={ref} style={[styles.box, style]} />;
};

useColorAnimation()

Creates animated color values with helper functions.

import { useColorAnimation } from "react-native-gsap";

const ColorCycler = () => {
  const { animatedColor, animateTo, animateSequence } = useColorAnimation(
    ["#3498db", "#e74c3c", "#f39c12", "#2ecc71", "#9b59b6"],
    0 // start index
  );

  return (
    <View>
      <Animated.View style={[styles.box, { backgroundColor: animatedColor }]} />
      <TouchableOpacity onPress={() => animateTo(1, 500)}>
        <Text>Red</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={() => animateSequence(3000)}>
        <Text>Cycle All Colors</Text>
      </TouchableOpacity>
    </View>
  );
};

GSAP.useGSAP()

Provides scoped animation methods with automatic cleanup.

const ScopedAnimations = () => {
  const boxRef = useAnimatedRef();
  const { to, from, timeline, kill } = GSAP.useGSAP();

  useEffect(() => {
    to(boxRef.current, 1, { x: 100, rotation: 360 });
    return () => kill(); // Auto cleanup
  }, []);

  const playTimeline = () => {
    const tl = timeline();
    tl.to(boxRef.current, 0.5, { x: 200 })
      .to(boxRef.current, 0.5, { x: 0 });
    tl.play();
  };

  return <GSAP.View ref={boxRef} style={styles.box} />;
};

🧩 Animated Components

All standard React Native components are available as animated versions:

import {
  AnimatedView,
  AnimatedText,
  AnimatedImage,
  AnimatedScrollView,
  AnimatedFlatList,
  AnimatedSectionList,
} from "react-native-gsap";

// Or via the GSAP namespace
<GSAP.View ref={ref} style={styles.box} />
<GSAP.Text ref={textRef}>Animated Text</GSAP.Text>
<GSAP.Image ref={imageRef} source={{ uri: "..." }} style={styles.image} />

<GSAP.FlatList
  ref={listRef}
  data={data}
  renderItem={({ item }) => <ItemComponent item={item} />}
  keyExtractor={(item) => item.id}
/>

<GSAP.ScrollView ref={scrollRef}>
  <GSAP.View ref={headerRef} style={styles.header} />
  <GSAP.View ref={contentRef} style={styles.content} />
</GSAP.ScrollView>

📈 Easing Functions

| Category | Easing Names | |----------|-------------| | Power | power1.in, power1.out, power1.inOut … power4.in/out/inOut | | Back | back.in, back.out, back.inOut | | Elastic | elastic.in, elastic.out, elastic.inOut | | Bounce | bounce.in, bounce.out, bounce.inOut | | Sine | sine.in, sine.out, sine.inOut | | Quad | quad.in, quad.out, quad.inOut | | Cubic | cubic.in, cubic.out, cubic.inOut | | Expo | expo.in, expo.out, expo.inOut | | Circ | circ.in, circ.out, circ.inOut | | Linear | linear |

// Standard easing
GSAP.to(boxRef.current, 1, { x: 100, ease: "elastic.out" });

// Easing with custom parameters
GSAP.to(boxRef.current, 1, { x: 100, ease: "elastic.out(1, 0.3)" });

// Custom cubic-bezier
GSAP.to(boxRef.current, 1, { scale: 1.5, ease: [0.42, 0, 0.58, 1] });

🔧 Utility Methods

GSAP.getAnimatedStyle(ref)

Returns the current animated style of a component.

const style = GSAP.getAnimatedStyle(boxRef);
console.log(style); // { transform: [...], backgroundColor: ... }

GSAP.getEasing(easeName)

Returns a bezier easing function for direct use with the Animated API.

const easing = GSAP.getEasing("power2.out");
Animated.timing(value, { toValue: 100, duration: 1000, easing, useNativeDriver: false }).start();

GSAP.createAnimatedValue(initial)

Creates an Animated.Value instance.

const opacity = GSAP.createAnimatedValue(1);
const translateX = GSAP.createAnimatedValue(0);

GSAP.interpolateColor(value, colors)

Creates a color interpolation.

const colorProgress = GSAP.createAnimatedValue(0);
const backgroundColor = GSAP.interpolateColor(colorProgress, ["#3498db", "#e74c3c"]);

<Animated.View style={[styles.box, { backgroundColor }]} />

GSAP.animateColors(ref, colors, duration, onComplete)

Animates through multiple colors sequentially.

GSAP.animateColors(
  boxRef,
  ["#3498db", "#e74c3c", "#f39c12", "#2ecc71"],
  2000,
  () => console.log("Done")
);

GSAP.killAll()

Stops all running animations. Ideal for cleanup on unmount.

useEffect(() => {
  return () => GSAP.killAll();
}, []);

📚 API Reference

Core Methods

| Method | Description | |--------|-------------| | GSAP.to(target, duration, vars) | Animate to values | | GSAP.from(target, duration, vars) | Animate from values | | GSAP.fromTo(target, duration, fromVars, toVars) | Animate between two sets of values | | GSAP.set(target, vars) | Set values instantly (no animation) |

Timeline Methods

| Method | Description | |--------|-------------| | GSAP.timeline(vars) | Create a timeline | | timeline.to(target, duration, vars, position) | Add a to animation | | timeline.from(target, duration, vars, position) | Add a from animation | | timeline.fromTo(target, duration, fromVars, toVars, position) | Add a fromTo animation | | timeline.play() | Play | | timeline.pause() | Pause | | timeline.resume() | Resume | | timeline.reverse() | Reverse | | timeline.restart() | Restart | | timeline.kill() | Kill | | timeline.progressTo(value) | Jump to progress (0–1) |

Stagger Methods

| Method | Description | |--------|-------------| | GSAP.stagger(targets, duration, vars, staggerAmount) | Stagger to values | | GSAP.staggerFrom(targets, duration, vars, staggerAmount) | Stagger from values | | GSAP.staggerTo(targets, duration, vars, staggerAmount) | Alias for staggerTo | | staggerResult.play/pause/resume/reverse/restart/kill() | Playback controls |

Hooks

| Hook | Description | |------|-------------| | useAnimatedRef() | Creates a ref for animated components | | useGSAPAnimation() | Returns ref and auto-updating style | | useColorAnimation(colors, startIndex) | Color animation utilities | | GSAP.useGSAP() | Scoped animation methods with auto-cleanup |

Animated Components

| Component | Description | |-----------|-------------| | GSAP.View / AnimatedView | Animated View | | GSAP.Text / AnimatedText | Animated Text | | GSAP.Image / AnimatedImage | Animated Image | | GSAP.ScrollView / AnimatedScrollView | Animated ScrollView | | GSAP.FlatList / AnimatedFlatList | Animated FlatList | | GSAP.SectionList / AnimatedSectionList | Animated SectionList |

Utility Methods

| Method | Description | |--------|-------------| | GSAP.getAnimatedStyle(ref) | Get current animated style | | GSAP.getEasing(easeName) | Get easing function | | GSAP.createAnimatedValue(initial) | Create Animated.Value | | GSAP.interpolateColor(value, colors) | Create color interpolation | | GSAP.animateColors(ref, colors, duration, onComplete) | Animate through color sequence | | GSAP.killAll() | Stop all animations |

🐛 Troubleshooting

Animation not playing

Make sure the ref is attached to a GSAP component, not a plain View:

// ✅ Correct
<GSAP.View ref={boxRef} style={styles.box} />

// ❌ Wrong
<View ref={boxRef} style={styles.box} />

Colors not animating smoothly

Use the built-in color helpers for smooth transitions:

// ✅ Direct color animation
GSAP.to(ref.current, 1, { backgroundColor: "#e74c3c" });

// ✅ For sequences, use useColorAnimation
const { animatedColor } = useColorAnimation(["#3498db", "#e74c3c"]);

Transform properties not working

Use the shorthand property names, not the transform array style:

// ✅ Correct
GSAP.to(ref.current, 1, { x: 100, y: 50, rotation: 360, scale: 1.5 });

// ❌ Wrong
GSAP.to(ref.current, 1, { translateX: 100, translateY: 50 });

Memory leaks

Always clean up animations when the component unmounts:

useEffect(() => {
  const anim = GSAP.to(ref.current, 1, { x: 100 });
  return () => anim.kill();
}, []);

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create your feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add some amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request