Dependencies · Animation

Migrating React Native Reanimated 2 to 3, and on to 4

Q: How do I check which Reanimated version my app uses?

Run npm ls react-native-reanimated (or yarn why react-native-reanimated) in the project, or look for it in your lockfile. The version in package.json is only the range you requested.

Published May 20, 2026 · Updated September 13, 2026 · 8 minute read

TL;DR

Reanimated 4.6.0 is the current release, and Reanimated 4 runs only on the New Architecture. Reanimated 3 and 2 are no longer actively maintained, according to their own documentation.

Going from 2 to 3 is mostly not an API migration: the official guide says v2 API code works in 3.x without changes, and 3.x drops only the old v1 API. The real work is React Native version and native build compatibility.

Going from 3 to 4 has a short list of real breaking changes: the New Architecture, the new react-native-worklets dependency and Babel plugin, renamed worklet functions, withSpring changes, and a few removed APIs.

Which Reanimated major you can use is decided by your React Native version and architecture. Plan it together with the React Native upgrade.

On this page

Where each version stands
Which major your React Native version allows
Reanimated 2 to 3
Reanimated 3 to 4
Babel configuration by version
Replacing useAnimatedGestureHandler
Common errors
Testing the migration
FAQ

Where each version stands

Reanimated major versions, from npm and the Reanimated compatibility guide
Major	Latest release	Status	Architecture
4.x	4.6.0 (August 21, 2026)	Current. 4.6.0 supports React Native 0.83–0.87 with react-native-worklets 0.12.x	New Architecture only
3.x	3.19.5 (December 22, 2025)	No longer actively maintained	Legacy and New Architecture
2.x	2.17.0 (April 24, 2023)	No longer actively maintained	Legacy Architecture

Sources: npm registry, Reanimated compatibility guide. Verified September 13, 2026.

The React Native support status page has the matching React Native versions.

Which major your React Native version allows

From the official compatibility tables (4.x, 3.x, 2.x), assuming the latest patch of each Reanimated minor:

Your app	Reanimated you can use
React Native 0.71 or older, Legacy Architecture	2.x (2.14 to 2.17 cover 0.63 to 0.71) or an early 3.x
React Native 0.72 to 0.81	3.x (3.19 covers 0.78 to 0.81 on both architectures); 4.x on the New Architecture from 0.78
React Native 0.82 or later (New Architecture only)	4.x only. No 3.x release supports 0.82 or later.
Latest React Native	Reanimated 4.6.0 supports React Native 0.83–0.87 with react-native-worklets 0.12.x

If you're on Expo, the SDK pins a Reanimated version for you; use npx expo install react-native-reanimated to get the matching one.

Reanimated 2 to 3

Scope: apps on Reanimated 2.x, React Native 0.71 or older.

The official 2.x to 3.x guide is short: Reanimated 3 doesn't introduce breaking changes to the v2 API, and all code written against the v2 API works in 3.x without changes. What 3.x removes is the Reanimated v1 API.

So the work is:

Find v1 API usage. Anything still using the Reanimated 1 API (for example, the old Animated.Value-style nodes imported from react-native-reanimated) has to move to the v2 API (shared values, useAnimatedStyle, withTiming) before or during the upgrade.
Pick a 3.x version for your React Native version. Use the compatibility table, not @latest: npm install react-native-reanimated@latest installs 4.x today, which needs the New Architecture.
Rebuild the native apps. Reinstall pods on iOS and do a clean Android build after changing the version.

Reanimated 3 also added support for the New Architecture (Fabric), which Reanimated 2 never had. That makes 3.x the bridge for apps that need to move to the New Architecture before React Native 0.82.

Reanimated 3 to 4

Scope: apps on the New Architecture, or moving to React Native 0.82 or later. From the official 3.x to 4.x guide:

New Architecture only. Reanimated 4 drops the Legacy Architecture and the Paper renderer. If you can't move yet, stay on the latest 3.x.
Install react-native-worklets in the version the compatibility table lists for your Reanimated version, then rebuild the native apps.
Change the Babel plugin from react-native-reanimated/plugin to react-native-worklets/plugin. The old path is still exported, but the guide recommends the new one.
Update worklet function imports to react-native-worklets. The old exports from Reanimated are deprecated: runOnJS becomes scheduleOnRN, runOnUI becomes scheduleOnUI, executeOnUIRuntimeSync becomes runOnUISync, and runOnRuntime becomes scheduleOnRuntime. Arguments are now passed directly instead of through a second call.
Check withSpring. restDisplacementThreshold and restSpeedThreshold are replaced by energyThreshold, duration is now perceptual (actual time is 1.5 times longer), and the defaults changed. The old defaults are importable as Reanimated3DefaultSpringConfig.
Remove APIs that are gone: useAnimatedGestureHandler, useWorkletCallback, and combineTransition. addWhitelistedNativeProps and addWhitelistedUIProps are now no-ops.
Rename useScrollViewOffset to useScrollOffset.
Check dependents. The guide calls out @gorhom/bottom-sheet 5.1.8 or newer. Reanimated 4 also drops support for the react-native-v8 engine.

Babel configuration by version

The Reanimated (or, in 4.x, Worklets) Babel plugin has to be listed last in babel.config.js, per the getting started guide. The preset name also changed with React Native: new projects used metro-react-native-babel-preset through 0.72 and @react-native/babel-preset from 0.73.

Reanimated 4, React Native 0.73 or later:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // ...other plugins...
    'react-native-worklets/plugin', // must be last
  ],
};

Reanimated 2 or 3:

module.exports = {
  presets: ['module:@react-native/babel-preset'], // 'module:metro-react-native-babel-preset' on 0.72 and older
  plugins: [
    // ...other plugins...
    'react-native-reanimated/plugin', // must be last
  ],
};

Expo projects get the plugin through Expo's Babel preset; the Reanimated docs note the Expo template has included it since SDK 50.

Replacing useAnimatedGestureHandler

useAnimatedGestureHandler was deprecated in Reanimated 3 and removed in 4. Replace it with the Gesture API from React Native Gesture Handler 2, passing callbacks directly. You can do this while still on 3.x, which makes the later move to 4 smaller.

Old:

const gestureHandler = useAnimatedGestureHandler({
  onStart: (_, ctx) => { ctx.startX = x.value; },
  onActive: (e, ctx) => { x.value = ctx.startX + e.translationX; },
});

return (
  <PanGestureHandler onGestureEvent={gestureHandler}>
    <Animated.View style={animatedStyle} />
  </PanGestureHandler>
);

New:

const startX = useSharedValue(0);

const pan = Gesture.Pan()
  .onStart(() => { startX.value = x.value; })
  .onUpdate((e) => { x.value = startX.value + e.translationX; });

return (
  <GestureDetector gesture={pan}>
    <Animated.View style={animatedStyle} />
  </GestureDetector>
);

Check the React Native Gesture Handler docs for the version that matches your React Native and Reanimated versions before upgrading it alongside.

Common errors

Worklet errors at runtime after changing Babel config. Confirm the plugin is last, then restart Metro with a clean cache: npx react-native start --reset-cache (or npx expo start --clear).
"Cannot find module 'react-native-worklets/plugin'". You're on Reanimated 4 without react-native-worklets installed, or with the wrong version. Install the version from the compatibility table.
Reanimated 3 behaves oddly or fails to build with react-native-worklets present. The compatibility guide says Reanimated 3 does not work with react-native-worklets installed. Remove it if you're staying on 3.x.
Build fails right after installing @latest. @latest is 4.x. On the Legacy Architecture, install a 3.x version that matches your React Native version instead.
iOS build fails after the version change. Reinstall pods (cd ios && pod install) and clean the build folder before investigating further.

Testing the migration

Animation regressions don't show up in unit tests. The migration's test plan is manual exercise of the screens that use animations.

The screens to hit:

Every screen with a layout animation (enter, exit, position transition)
Every gesture-driven UI (swipe to dismiss, pan-to-pull, pinch-to-zoom)
Every scroll-driven animation (parallax header, sticky header reveal)
Every spring animation, if you're moving to 4.x and its withSpring defaults
Anything driven from useAnimatedReaction or chained derived values

Smooth on iOS doesn't imply smooth on Android. Test both, and include a low-end Android device, not just an emulator.

Stuck mid-Reanimated migration?

Reanimated upgrades usually arrive tangled with a React Native and New Architecture upgrade. Run the free scanner to see which installed package versions have published security advisories, then get a fixed-price quote.

Run Free Scanner → Get a Fixed-Price Quote

Frequently Asked Questions

What is the current version of React Native Reanimated?

Reanimated 4.6.0 is the latest release on npm. It supports React Native 0.83–0.87 and requires react-native-worklets 0.12.x and the New Architecture. Reanimated 3's last release is 3.19.5.

Is Reanimated 2 or 3 still supported?

Both are documented as no longer actively maintained. Reanimated 2 supports React Native up to 0.71, and no Reanimated 3 release supports React Native 0.82 or later, where the New Architecture is the only option. Staying current on React Native means moving to Reanimated 4.

What are the breaking changes from Reanimated 2 to 3?

For code written against the v2 API, none: the official migration guide says it works in 3.x without changes. Reanimated 3 removes the old v1 API, so any v1-style code must be rewritten. Expect version-compatibility and native rebuild work rather than an API rewrite.

What are the breaking changes from Reanimated 3 to 4?

Reanimated 4 requires the New Architecture and the react-native-worklets package, moves the Babel plugin to react-native-worklets/plugin, renames runOnJS, runOnUI, and related worklet functions, changes withSpring configuration and defaults, removes useAnimatedGestureHandler, useWorkletCallback, and combineTransition, and renames useScrollViewOffset to useScrollOffset.

Does Reanimated 3 require the New Architecture?

No. Reanimated 3 supports both the Legacy Architecture and the New Architecture, within the React Native ranges in its compatibility table. Reanimated 4 requires the New Architecture, and Reanimated 2 does not support it.

How do I check which Reanimated version my app uses?

Run npm ls react-native-reanimated (or yarn why react-native-reanimated) in the project, or look for it in your lockfile. The version in package.json is only the range you requested.