{"id":11794,"library":"react-native-reanimated","title":"React Native Reanimated","description":"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.","status":"active","version":"4.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/software-mansion/react-native-reanimated","tags":["javascript","react-native","react","native","reanimated","typescript"],"install":[{"cmd":"npm install react-native-reanimated","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-reanimated","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-reanimated","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React dependency for all React Native projects.","package":"react","optional":false},{"reason":"Core React Native platform dependency. Specific version compatibility is crucial for native module linking.","package":"react-native","optional":false},{"reason":"Essential for enabling worklets and running code on the UI thread. Strict version compatibility with `react-native-reanimated` is required.","package":"react-native-worklets","optional":false}],"imports":[{"note":"`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.","wrong":"import { SharedValue } from 'react-native-reanimated';","symbol":"useSharedValue","correct":"import { useSharedValue } from 'react-native-reanimated';"},{"note":"`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.","wrong":"import { AnimatedStyle } from 'react-native-reanimated';","symbol":"useAnimatedStyle","correct":"import { useAnimatedStyle } from 'react-native-reanimated';"},{"note":"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.","wrong":"const Animated = require('react-native-reanimated');","symbol":"Animated","correct":"import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';"},{"note":"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.","symbol":"runOnJS","correct":"import { runOnJS } from 'react-native-reanimated';"}],"quickstart":{"code":"import React from 'react';\nimport { Button, View, StyleSheet } from 'react-native';\nimport Animated, {\n  useSharedValue,\n  useAnimatedStyle,\n  withSpring,\n} from 'react-native-reanimated';\n\nconst Box = () => {\n  const offset = useSharedValue(0);\n\n  const animatedStyles = useAnimatedStyle(() => {\n    // Animations run on the UI thread here\n    return {\n      transform: [\n        { translateX: withSpring(offset.value * 255) },\n      ],\n    };\n  });\n\n  const handlePress = () => {\n    offset.value = Math.random(); // Update shared value from JS thread\n  };\n\n  return (\n    <View style={styles.container}>\n      <Animated.View style={[styles.box, animatedStyles]} />\n      <Button onPress={handlePress} title=\"Move\" />\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    alignItems: 'center',\n    justifyContent: 'center',\n  },\n  box: {\n    width: 100,\n    height: 100,\n    backgroundColor: 'purple',\n    borderRadius: 10,\n    marginBottom: 20,\n  },\n});\n\nexport default Box;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `useAnimatedKeyboard` hook has been deprecated and its functionality is now intended to be handled by the external `react-native-keyboard-controller` library.","severity":"deprecated","affected_versions":">=4.3.0-rc.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"Stricter peer dependency validation for `react-native` and `react-native-worklets` can cause build failures or runtime crashes if versions are mismatched.","severity":"breaking","affected_versions":">=4.2.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Invariant Violation: `worklet` must be a function."},{"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.","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.","error":"ERROR Invariant Violation: `new NativeReanimatedModule()` cannot be found. This typically happens when the native module is not linked correctly."},{"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.","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.","error":"TypeError: Cannot read property 'value' of undefined at anonymous function"},{"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.","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.","error":"Invariant Violation: Calling `toJSON` on the 'Reanimated' module is not supported."}],"ecosystem":"npm"}