Registry / web-framework / react-native-reanimated

react-native-reanimated

library4.3.0jsnpmunverified

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.

web-framework

npm install react-native-reanimated

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-REANI

react-native-reanimated

web-frameworkjavascriptv4.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useSharedValue

✓ import { useSharedValue } from 'react-native-reanimated';

✗ import { SharedValue } 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

✓ import { useAnimatedStyle } from 'react-native-reanimated';

✗ import { AnimatedStyle } 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

✓ import Animated, { useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';

✗ const Animated = require('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.

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;

Debug

Known issues

breakingReanimated 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.

affects: >=2.0.0

gotchaIncorrect 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.

affects: >=2.0.0

deprecatedThe `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.

affects: >=4.3.0-rc.0

gotchaExpo 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.

affects: >=4.0.0

breakingStricter 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.

affects: >=4.2.3

Errors

Common errors & fixes

Invariant Violation: `worklet` must be a function.

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.

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

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.

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.

Upgrade

Version history

4.3.0latest on npm

Audit

Dependencies

reactrequiredCore React dependency for all React Native projects.

react-nativerequiredCore React Native platform dependency. Specific version compatibility is crucial for native module linking.

react-native-workletsrequiredEssential for enabling worklets and running code on the UI thread. Strict version compatibility with `react-native-reanimated` is required.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/software-mansion/react-native-reanimated ↗

packagehttps://www.npmjs.com/package/react-native-reanimated ↗

homepagehttps://docs.swmansion.com/react-native-reanimated ↗