React Native Animation

React Native Animation

Implements performant animations in React Native using Reanimated 3 for UI thread execution, the Animated API with native driver for simpler cases, gesture-driven interactions via react-native-gesture-handler, and LayoutAnimation for implicit transitions. Keeps animations running at 60fps without blocking the JS thread.

TL;DR Checklist

• Use Reanimated (useSharedValue + useAnimatedStyle) for all interactive animations
• Set useNativeDriver: true for transform/opacity animations with Animated API
• Never animate layout properties (width, height, top, left) on the JS thread
• Use LayoutAnimation for implied layout changes (add/remove items)
• Clean up all animation refs and listeners on component unmount
• Use InteractionManager.runAfterInteractions for deferred non-critical work

When to Use

Use this skill when:

• Building gesture-driven interactions (drag, pinch, swipe, rotate)
• Implementing shared element transitions between screens
• Creating micro-interactions (button press, card flip, list reorder)
• Animating component mount/unmount with enter/exit transitions
• Adding scroll-driven animations (parallax, header collapse, progress bars)
• Building skeleton loading animations or shimmer effects

When NOT to Use

Avoid this skill for:

• Simple opacity or transform transitions — use Animated API (lighter weight)
• CSS-animatable properties in React Native Web (prefer CSS animations)
• Navigation transitions already handled by React Navigation
• Layout changes that don't require animation (use plain state toggles)
• Situations where InteractionManager is sufficient for deferring work

Core Workflow

1. Choose Animation Library — Reanimated for complex/interactive animations (UI thread), Animated API for simple declarative animations with native driver.

2. Set Up Shared/Animated Values — useSharedValue (Reanimated) or useRef(new Animated.Value()) for Animated API.

3. Define Animated Styles — useAnimatedStyle (Reanimated) or interpolate values to style props.

4. Trigger with Timing/Spring/Gestures — Apply withTiming/withSpring for declarative curves, or attach to gesture handlers.

5. Wire Up Gesture Handlers — Use react-native-gesture-handler PanGestureHandler, PinchGestureHandler, etc. with Reanimated worklets.

6. Clean Up — Cancel running animations, remove listeners, and reset refs on unmount.

Implementation Patterns

Pattern 1: Reanimated with Gesture Handler (Fade-In Card)

// ✅ GOOD: Reanimated on UI thread — smooth 60fps
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  withSpring,
  Easing,
} from 'react-native-reanimated';
import { TapGestureHandler, State } from 'react-native-gesture-handler';

function AnimatedCard() {
  const opacity = useSharedValue(0);
  const scale = useSharedValue(1);

  // Mount animation
  useEffect(() => {
    opacity.value = withTiming(1, {
      duration: 400,
      easing: Easing.out(Easing.cubic),
    });
  }, []);

  // Press animation with spring
  const animatedStyle = useAnimatedStyle(() => ({
    opacity: opacity.value,
    transform: [{ scale: scale.value }],
  }));

  const GestureEvent) => {
    if (event.nativeEvent.state === State.BEGAN) {
      scale.value = withSpring(0.96);
    } else if (event.nativeEvent.state === State.END) {
      scale.value = withSpring(1);
    }
  };

  return (
    <TapGestureHandler
      <Animated.View style={[styles.card, animatedStyle]}>
        <Text>Animated Card Content</Text>
      </Animated.View>
    </TapGestureHandler>
  );
}

Pattern 2: Animated API with Native Driver (BAD vs. GOOD)

// ❌ BAD: Animating layout property on JS thread — janky
const animatedValue = useRef(new Animated.Value(0)).current;

const startBadAnimation = () => {
  Animated.timing(animatedValue, {
    toValue: 100,
    duration: 300,
    useNativeDriver: false, // Layout props require JS thread
  }).start();
};

return (
  <Animated.View style={{ width: animatedValue }}> // width = JS thread
    <Text>Bad — animates width on JS thread</Text>
  </Animated.View>
);

// ✅ GOOD: Animating transform on native thread — smooth 60fps
const translateX = useRef(new Animated.Value(0)).current;
const opacity = useRef(new Animated.Value(1)).current;

const startGoodAnimation = () => {
  Animated.parallel([
    Animated.timing(translateX, {
      toValue: 100,
      duration: 300,
      useNativeDriver: true, // transform supports native driver
    }),
    Animated.timing(opacity, {
      toValue: 0.5,
      duration: 300,
      useNativeDriver: true, // opacity supports native driver
    }),
  ]).start();
};

return (
  <Animated.View
    style={{
      opacity,
      transform: [{ translateX }],
    }}
  >
    <Text>Good — animates transform on native thread</Text>
  </Animated.View>
);

Pattern 3: LayoutAnimation for Implicit Transitions

// ✅ GOOD: LayoutAnimation handles the implied layout change smoothly
import { LayoutAnimation, Platform, UIManager } from 'react-native';

// Required for Android
if (
  Platform.OS === 'android' &&
  UIManager.setLayoutAnimationEnabledExperimental
) {
  UIManager.setLayoutAnimationEnabledExperimental(true);
}

function ExpandableSection({ title, children }: ExpandableProps) {
  const [isExpanded, setIsExpanded] = useState(false);

  const toggleExpand = () => {
    LayoutAnimation.configureNext(
      LayoutAnimation.create(
        300,
        LayoutAnimation.Types.easeInEaseOut,
        LayoutAnimation.Properties.opacity
      )
    );
    setIsExpanded((prev) => !prev);
  };

  return (
    <View>
      <TouchableOpacity
        <Text style={styles.title}>{title}</Text>
      </TouchableOpacity>
      {isExpanded && <View>{children}</View>}
    </View>
  );
}

Pattern 4: InteractionManager for Deferred Work

// ✅ GOOD: Defer non-critical work until after animations complete
function ProfileScreen({ userId }: { userId: string }) {
  const [analyticsLoaded, setAnalyticsLoaded] = useState(false);

  useEffect(() => {
    const task = InteractionManager.runAfterInteractions(() => {
      // This runs after all animations and transitions complete
      loadAnalytics(userId).then(() => setAnalyticsLoaded(true));
    });

    return () => task.cancel();
  }, [userId]);

  return (
    <View>
      <ProfileHeader userId={userId} />
      {analyticsLoaded ? (
        <AnalyticsCharts userId={userId} />
      ) : (
        <ActivityIndicator />
      )}
    </View>
  );
}

Constraints

MUST DO

• Use Reanimated (useSharedValue, useAnimatedStyle) for complex animations on the UI thread
• Set useNativeDriver: true for transform and opacity animations when using Animated API
• Use LayoutAnimation.configureNext for implied layout changes (add/remove elements)
• Use InteractionManager.runAfterInteractions to defer data fetching and analytics
• Animate only transform (translateX, translateY, scale, rotate) and opacity for native-driver support
• Cancel running animations and remove event listeners on component unmount

MUST NOT DO

• Animate layout properties (width, height, top, left) on the JS thread — use transform: [{ translateX }]
• Create a new Animated.Value on every render — store in ref or use useSharedValue
• Block the UI thread with heavy computation during active animations
• Forget to clean up animation refs, listener subscriptions, or gesture handlers on unmount
• Use useNativeDriver: false unless animating non-transform/non-opacity properties
• Apply Reanimated worklets to callbacks that touch JS state — worklets run on the UI thread

Related Skills

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• React Native Reanimated 3 Documentation
• React Native Animated API Reference
• React Native LayoutAnimation
• InteractionManager
• react-native-gesture-handler
• React Native Performance: Using Native Driver
• Reanimated Shared Value Transitions