React Native Reanimated

4.3.0 · active · verified Sun Apr 19

React Native Reanimated is a high-performance animation library for React Native, offering a powerful and flexible alternative to the built-in `Animated` API. It enables animations to run directly on the native UI thread, completely decoupling them from the JavaScript thread, which results in significantly smoother and more reliable user experiences, especially under heavy load or during complex interactions. The current stable version is 4.3.0, with frequent patch and minor updates. The library maintains a rapid release cadence, often introducing core infrastructure improvements via the tightly coupled `react-native-worklets` package, like the recent `Shareable` memory type. Key differentiators include its worklet-based architecture, allowing direct UI thread execution of JavaScript functions, and recent advancements such as CSS SVG animations for `Path`, `Image`, `LinearGradient`, `RadialGradient`, `Pattern`, and `Text` components, including advanced path morphing capabilities.

Common errors

```
Invariant Violation: `worklet` must be a function.
```
cause The Babel plugin is not processing your code correctly, meaning functions marked as worklets are not being recognized or transformed for UI thread execution.

fix Double-check that `react-native-reanimated/plugin` is correctly installed and listed as the *last* plugin in your `babel.config.js`. After modification, clear your Metro cache (`npx react-native start --reset-cache`) and rebuild your application.
```
ERROR Invariant Violation: `new NativeReanimatedModule()` cannot be found. This typically happens when the native module is not linked correctly.
```
cause The native module for Reanimated is not properly linked or loaded into your React Native project, which often occurs after an initial installation, upgrade, or if the project configuration is incorrect.

fix For bare React Native projects, ensure `pod install` (iOS) or `npx react-native run-android` (Android) has been executed after installation. For Expo projects, you *must* use a custom development client (`expo prebuild` and `eas build --profile development`) as Reanimated is a native module.
```
TypeError: Cannot read property 'value' of undefined at anonymous function
```
cause You are attempting to access the `.value` property of a `SharedValue` that is either not initialized, or is `undefined` because it was not correctly created with `useSharedValue` or passed down.

fix Ensure that any variable you expect to be a `SharedValue` is properly initialized using `useSharedValue(initialValue)` before accessing its `.value` property. Verify correct prop drilling if passing shared values between components.
```
Invariant Violation: Calling `toJSON` on the 'Reanimated' module is not supported.
```
cause This error typically occurs during Jest tests when the Reanimated native module is mocked incorrectly or not mocked at all, and a test tries to serialize it.

fix Configure Jest to mock `react-native-reanimated` properly. A common approach is to use `jest.mock('react-native-reanimated', () => require('react-native-reanimated/mock'));` in your Jest setup file.

Warnings

breaking Reanimated v2 (and subsequent major versions like v3 and v4) introduced a fundamentally new API centered around hooks and worklets, deprecating the imperative API from v1. Existing v1 code requires a full rewrite.
Fix: Migrate all animation logic to the new hooks-based API using `useSharedValue`, `useAnimatedStyle`, `withTiming`, `withSpring`, etc. Consult the official migration guides for detailed steps between major versions.
gotcha Incorrect or missing Babel plugin configuration (`react-native-reanimated/plugin`) will prevent worklets from being correctly transformed and lead to runtime errors, as functions intended for the UI thread won't be recognized.
Fix: Ensure `react-native-reanimated/plugin` is correctly listed as the *last* plugin in your `babel.config.js` file. Example: `plugins: [['react-native-reanimated/plugin']]`. Clear your Metro cache and rebuild the app afterwards.
deprecated The `useAnimatedKeyboard` hook has been deprecated and its functionality is now intended to be handled by the external `react-native-keyboard-controller` library.
Fix: Refactor code using `useAnimatedKeyboard` to integrate with `react-native-keyboard-controller`. Refer to the `react-native-keyboard-controller` documentation for the new implementation details.
gotcha Expo Go does not support static feature flags, which are integral to certain optimizations within Reanimated. Attempting to use these flags in Expo Go might result in unexpected behavior or build failures.
Fix: For projects requiring static feature flags or advanced native module capabilities, use a custom development client (Expo Development Build) instead of the standard Expo Go client.
breaking Stricter peer dependency validation for `react-native` and `react-native-worklets` can cause build failures or runtime crashes if versions are mismatched.
Fix: Always ensure that your `react-native` and `react-native-worklets` versions precisely match the peer dependency requirements specified in `react-native-reanimated`'s `package.json` for your installed version.

Install

npm install react-native-reanimated npm
yarn add react-native-reanimated yarn
pnpm add react-native-reanimated pnpm

Imports

useSharedValue
wrong:
```
import { SharedValue } from 'react-native-reanimated';
```
correct:
```
import { useSharedValue } from 'react-native-reanimated';
```
`useSharedValue` is a hook for creating mutable values that can be shared between the UI and JS threads. `SharedValue` is the type definition, not the hook for instantiation.
useAnimatedStyle
wrong:
```
import { AnimatedStyle } from 'react-native-reanimated';
```
correct:
```
import { useAnimatedStyle } from 'react-native-reanimated';
```
`useAnimatedStyle` is a hook used within a functional component to define styles that will be animated directly on the UI thread. Use it for dynamic styling.
Animated
wrong:
```
const Animated = require('react-native-reanimated');
```
correct:
```
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
```
Reanimated v2 and newer versions are designed for ESM and modern React Native. While a default `Animated` export exists (e.g., for `Animated.View`), the primary API is exposed via named imports for hooks and utilities. CommonJS `require` should generally be avoided for contemporary usage.
runOnJS
```
import { runOnJS } from 'react-native-reanimated';
```
This utility function allows you to execute a JavaScript function from within a UI thread worklet. It's critical for handling side effects like state updates from UI thread animations.

Quickstart

This quickstart demonstrates a basic animation where a box's horizontal position is animated using `useSharedValue` and `useAnimatedStyle` with a spring effect upon button press. This showcases UI thread animation.

import React from 'react';
import { Button, View, StyleSheet } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';

const Box = () => {
  const offset = useSharedValue(0);

  const animatedStyles = useAnimatedStyle(() => {
    // Animations run on the UI thread here
    return {
      transform: [
        { translateX: withSpring(offset.value * 255) },
      ],
    };
  });

  const handlePress = () => {
    offset.value = Math.random(); // Update shared value from JS thread
  };

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, animatedStyles]} />
      <Button onPress={handlePress} title="Move" />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  box: {
    width: 100,
    height: 100,
    backgroundColor: 'purple',
    borderRadius: 10,
    marginBottom: 20,
  },
});

export default Box;

view raw JSON →