Gesture Handler v2 / v3 API

react-native-gesture-handler 3.x ships a new hooks-based gestures API (usePanGesture, usePinchGesture, ...) next to the 2.x builder API (Gesture.Pan(), Gesture.Pinch()). This library builds its zoom gesture with either one.

You do not have to configure anything. By default the API is detected from the react-native-gesture-handler version installed in your app:

Installed gesture handler	API used
3.x	v3 hooks API
2.x	v2 builder API

Detection happens at both levels: useZoomGesture and <Zoom /> pick the right one at runtime, and the type of zoomGesture resolves to the matching gesture type at compile time, so it is always accepted by the GestureDetector of your installed version.

Override it only if you need to - for example to stay on the v2 API after upgrading to react-native-gesture-handler 3.x.

Choosing per component

import Zoom from 'react-native-zoom-reanimated'

<Zoom gestureApi="v2">
  <Image source={{ uri: 'https://example.com/image.jpg' }} />
</Zoom>

gestureApi accepts 'auto' (default), 'v2' or 'v3'. Changing it on a mounted Zoom remounts its gesture tree.

Choosing app-wide

Call setGestureApiVersion once at startup, before rendering any Zoom. It sets the default used by useZoomGesture and by every Zoom that does not pass gestureApi itself.

import { setGestureApiVersion } from 'react-native-zoom-reanimated'

setGestureApiVersion('v2') // or 'v3', or 'auto' (the default)

A component keeps the version it resolved on its first render, so calling this later only affects new mounts.

Choosing in the hook API

useZoomGesture follows the same auto-detection. To pin a version at a single call site, import the version-specific hook instead:

import { useZoomGestureV2, useZoomGestureV3 } from 'react-native-zoom-reanimated'

// react-native-gesture-handler v2 builder API - works on 2.x and 3.x
const zoom = useZoomGestureV2({ maxScale: 6 })

// react-native-gesture-handler v3 hooks API - requires 3.x, throws otherwise
const zoom = useZoomGestureV3({ maxScale: 6 })

All three return the same shape; only the type of zoomGesture differs.

Capability check

import { isGestureApiV3Supported } from 'react-native-zoom-reanimated'

if (isGestureApiV3Supported()) {
  // react-native-gesture-handler >= 3 is installed
}