For AI agents: the complete documentation index is available at /2.x/llms.txt, the full documentation bundle is available at /2.x/llms-full.txt, and this page is available as Markdown at /2.x/guide/migration-from-1.x.md.
v3 is stable. See what changed
React Native Gesture Image Viewer
  • English
  • 2.x

      • Migrating from 1.x to 2.x

      Migration from Reanimated 3.x to 4.x

      Migration Steps

      Upgrade the react-native-reanimated package:

      npm
      yarn
      pnpm
      bun
      deno
      npm install react-native-reanimated

      Install the react-native-worklets package:

      npm
      yarn
      pnpm
      bun
      deno
      npm install react-native-worklets

      Update Configuration

      Expo

      Run prebuild to update the native code in the ios and android directories.

      npm
      yarn
      pnpm
      bun
      deno
      npm expo prebuild

      And that's it! Reanimated 4 is now configured in your Expo project.
      Since Expo SDK 50, the Expo starter template includes the Reanimated Babel plugin by default.

      React Native CLI

      When using the React Native Community CLI, you also need to manually add the react-native-worklets/plugin plugin to your babel.config.js.

      babel.config.js
      module.exports = {
  presets: [
    ... // don't add it here :)
  ],
  plugins: [
    ...
    // for web
    '@babel/plugin-transform-export-namespace-from',
-   'react-native-reanimated/plugin',
+   'react-native-worklets/plugin',
  ],
};

      Remove wrapWithReanimatedMetroConfig from your metro.config.js.

      metro.config.js
      - const { wrapWithReanimatedMetroConfig } = require('react-native-reanimated/metro-config');

const config = {
  // Your existing Metro configuration options
};

- module.exports = wrapWithReanimatedMetroConfig(config);
+ module.exports = config

      Remove currentIndex and totalCount from useGestureViewerController

      ❗ Breaking Change
      • useGestureViewerController no longer returns currentIndex and totalCount. Use useGestureViewerState instead.
      • Rename GestureViewerControllerState type to GestureViewerState
      import {
  GestureViewer,
- GestureViewerControllerState,
+ GestureViewerState
  useGestureViewerController,
  useGestureViewerEvent,
+ useGestureViewerState,
} from 'react-native-gesture-image-viewer';

const {
  goToIndex, goToPrevious, goToNext, zoomIn, zoomOut, resetZoom, rotate,
- currentIndex, totalCount
} = useGestureViewerController();

+ const { currentIndex, totalCount } = useGestureViewerState();

      Remove onIndexChange prop

      ❗ Breaking Change

      onIndexChange prop has been removed. Use useGestureViewerState with useEffect instead.

      // Before
<GestureViewer onIndexChange={(index) => console.log(index)} />;

// After
const { currentIndex } = useGestureViewerState();

useEffect(() => {
  console.log(currentIndex);
}, [currentIndex]);

      Rename gesture props

      Improve gesture prop naming for better developer experience.

      ❗ Breaking Change
      • enableDismissGesture → dismiss.enabled
      • dismissThreshold → dismiss.threshold
      • resistance → dismiss.resistance
      • animateBackdrop → dismiss.fadeBackdrop
      • useSnap → enableSnapMode
      • enableZoomPanGesture → enablePanWhenZoomed
      • enableZoomGesture → enablePinchZoom
      • enableSwipeGesture → enableHorizontalSwipe
      <GestureViewer
-  enableDismissGesture
-  dismissThreshold
-  resistance
-  animateBackdrop
+  dismiss={{
+    enabled: true,
+    threshold: 80,
+    resistance: 2,
+    fadeBackdrop: true,
+  }}

-  useSnap
+  enableSnapMode

-  enableZoomPanGesture
+  enablePanWhenZoomed

-  enableZoomGesture
+  enablePinchZoom

-  enableSwipeGesture
+  enableHorizontalSwipe
/>