npm / react-native-gesture-handler

react-native-gesture-handler

What changed in react-native-gesture-handler 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.

31 breaking2 deprecations21 new APIs and options1 performance21 behavior and defaults2 tooling133 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.1.1 on npm

react-native-gesture-handler 3153 changes

Breaking changes 28

Touchable supports immediate press-out behavior, with the prop renamed from pressOutAfterAnimation; Pressable can opt out of the behavior.
3.4.0release notes
shouldCancelWhenOutside now defaults to true.
3.3.0release notes
Adopts AGP v9, which may affect Android build compatibility for developers using the package.
2.33.0, 3.2.0release notes release notes
Buttons no longer call onPress while the keyboard is being dismissed.
3.1.0release notes
Opacity is removed from Swipeable action panels.
3.0.2release notes
Removes dispatchesReanimatedEvent from the initial config.
3.0.1release notes
The package no longer emits CommonJS output.
3.0.0release notes
Renames the Swipeable dragOffsetFrom*Edge prop.
3.0.0release notes
gestureHandlerRootHOC is removed; update applications that still use it.
3.0.0release notes
Detectors now throw an error if they are not placed inside GestureHandlerRootView.
3.0.0release notes
The prop is renamed to effect; update existing component props.
3.0.0release notes
InterceptingGestureDetector now throws when it is not rendered under GHRootView.
3.0.0release notes
Moves the end flag to the event passed to onDeactivate and onFinalize.
3.0.0release notes
The callback is renamed to onDeactivate; update gesture callback usage.
3.0.0release notes
The callback is renamed to onActivate; update gesture callback usage.
3.0.0release notes
The callback is renamed to onTouchesCancel; update existing callback usage.
3.0.0release notes
Support for the old Paper architecture is removed; Gesture Handler 3 is rebuilt for the New Architecture.
3.0.0release notes
RNGestureHandlerEnabledRootView is removed; update applications that still use it.
3.0.0release notes
Changes SwipeableProps ref types from RefObject to Ref.
2.31.2, 3.0.0release notes release notes
The field is renamed to handlerTag; update code that reads or supplies tag.
3.0.0release notes
Removes createNativeWrapper from Touchable.
3.0.0release notes
Uses a disabled prop instead of enabled on the button component.
3.0.0release notes
Removes the onActiveStateChange callback from Touchable.
3.0.0release notes
Adds the Touchable component, renamed from Clickable, as a button component for application code.
3.0.0release notes
Changes the order in which Touchable callbacks are invoked.
3.0.0release notes
Button activation timing changes; buttons no longer activate on start, and iOS activates them on pointer up.
3.0.0release notes
The hook is renamed to useCompetingGestures; update existing imports and calls.
3.0.0release notes
Adds the renamed native-gesture relation property for yielding to continuous gestures.
3.0.0release notes

Deprecations 1

The builder API is deprecated.
3.0.0release notes

New APIs and options 19

The legacy GestureDetector Wrap now exposes an animatable ref.
2.33.1, 3.4.0release notes release notes
Adds an imperative API for testing gesture handlers.
3.2.0release notes
Pressable is implemented based on Touchable.
3.2.0release notes
Exports the PressableEvent type for consumers to use.
2.33.0, 3.2.0release notes release notes
Touchable gains hover callbacks on Android, iOS, and Web.
3.2.0release notes
Adds delaysChildPressedState to the native gesture.
3.1.0release notes
Adds the rootContainerStyle prop to ReanimatedDrawerLayout.
3.0.1release notes
Adds a prop to gesture handlers for cancelling the JS responder.
3.0.0release notes
The missing cancelsTouchesInView option is added.
3.0.0release notes
Handlers gain a changeEventCalculator option.
3.0.0release notes
Gesture relations are introduced, with relation support also added for the web.
3.0.0release notes
Gesture Handler 3 introduces a new hook-based API for defining gestures.
3.0.0release notes
Adds a way to customize the out-animation duration for long press.
3.0.0release notes
A manualActivation prop is added for gestures.
3.0.0release notes
iOS Native gesture events now include numberOfPointers.
2.31.0, 3.0.0release notes release notes
runOnJS is added to gesture configuration.
3.0.0release notes
A StateManager API is introduced for gesture state management.
3.0.0release notes
Adds a prop to control cancellation when the pointer leaves the button.
3.0.0release notes
A new Touchable component is introduced.
3.0.0release notes

Behavior and default changes 19

Can now be called from the first onTouchesDown on Android, iOS, and Web.
3.4.0release notes
On Web, ScrollView now intercepts detectors.
3.4.0release notes
The Web maxDelay default now matches native at 200 ms.
3.4.0release notes
On Android, nested scrolling stops when a native handler's gesture ends.
3.3.0release notes
On web, the native gesture activates when a real scroll occurs rather than when pointer distance passes a threshold.
3.3.0release notes
GestureDetector now defaults moduleId to -1.
3.2.0release notes
Derives Pressable's pressed state from testOnly_pressed.
2.33.0, 3.2.0release notes release notes
Adds coordinates to Hover events on macOS.
2.33.0, 3.1.0release notes release notes
Native gesture events now emit coordinates.
3.1.0release notes
Touchable handles hover on Android and Apple platforms.
3.1.0release notes
The testID property is ignored in production environments.
3.0.2release notes
Uses v3 detectors in ReanimatedDrawerLayout.
3.0.1release notes
Gestures can now be created without configuration.
3.0.0release notes
GestureDetector can now have multiple children.
3.0.0release notes
Web Pinch and Rotation gestures are continuous.
3.0.0release notes
Changes Touchable's default underlay props.
3.0.0release notes
Adds hover effects for Touchable on the web.
3.0.0release notes
Button animations support reduced-motion preferences and animation scale.
3.0.0release notes
VirtualDetector is made part of the public API.
3.0.0release notes

Tooling 2

iOS builds now support Swift Package Manager.
3.4.0release notes
Type definitions now support TypeScript's exactOptionalPropertyTypes option.
2.31.0, 3.0.0release notes release notes

Fixes and other changes 84

On Web, changes to composed gestures are detected by the detector.
3.4.0release notes
On Android, detector gestures are cancelled when a native view above them takes over the touch.
3.4.0release notes
On Web, detector-owned DOM props are preserved across a full config replacement.
3.4.0release notes
On Web, event coordinates are mapped through the view's full transform.
3.4.0release notes
Late-mounted gesture objects are linked, and mount reactions without external relations are skipped.
3.4.0release notes
Detector frames now cover transformed children.
3.4.0release notes
Hidden and transparent buttons are skipped during hit testing.
2.33.1, 3.4.0release notes release notes
On iOS, manualActivation is no longer ignored after a config update during a gesture.
2.33.1, 3.4.0release notes release notes
Android gestures are cancelled on native ACTION_CANCEL.
3.4.0release notes
On iOS, flags are preserved across a partial config update.
3.4.0release notes
Android nested scrolling stops when the root starts intercepting.
2.33.1, 3.4.0release notes release notes
On Android, onPressIn is dispatched when the native press starts.
3.4.0release notes
On Android, the overflow ancestor pass is checked against the detector child's bounds.
3.4.0release notes
Android gesture root views now respect pointer events.
2.33.1, 3.4.0release notes release notes
Config values are resent from the UI thread after binding.
3.4.0release notes
Pan offset updates now follow the sign of the SharedValue on every update.
3.4.0release notes
On Android, Touchable presses are prevented when stopping ScrollView flings.
3.4.0release notes
On Web, view-relative coordinates are corrected for trackpad pan events.
2.33.1, 3.4.0release notes release notes
The ripple now forwards the borderless and foreground options.
3.3.0release notes
On Android, a parent handler waiting for a child no longer cancels that child.
3.3.0release notes
Keeps button hit testing within its own subtree on iOS.
2.33.0, 3.3.0release notes release notes
Preserves disabled button targets under box-none parents on iOS.
2.33.0, 3.3.0release notes release notes
On iOS, handlers detach when the detector view is recycled.
3.3.0release notes
An in-progress press is canceled on iOS and released on Android when the button is disabled.
3.3.0release notes
Resolves DrawerLayoutAndroid lazily to avoid an RN deprecation warning on import.
2.33.0, 3.3.0release notes release notes
Resets enableTrackpadTwoFingerGesture in the web PanGestureHandler.
2.33.0, 3.3.0release notes release notes
On web, replacing the full configuration resets NativeViewGestureHandler config, restores enabled, and refreshes the DOM.
3.3.0release notes
On web, handlers are removed from the orchestrator when disabled mid-gesture or when they never began.
3.3.0release notes
On Android, native handlers attach to the detector's child rather than a nested button.
3.3.0release notes
Presses no longer become unresponsive when the keyboard belongs to a native field.
3.3.0release notes
Resets numberOfPointers in LongPressGestureHandler.
2.33.0, 3.3.0release notes release notes
On Android, buttons no longer fire press events when a scroll takes over the touch.
3.3.0release notes
Fixes animation speed after rerender.
2.33.0, 3.3.0release notes release notes
Keeps native handlers stable when event callbacks change.
2.33.0, 3.3.0release notes release notes
Accumulated wheel delta is reset.
3.3.0release notes
Pressable props were updated; the notes do not specify which props changed.
3.2.1release notes
Forwards press handlers as testOnly_* in PressableWithTouchable.
3.2.1release notes
Fixes Fling touch event delivery and consistent begin/end states on macOS.
2.33.0, 3.2.0release notes release notes
Touchable now respects keyboardShouldPersistTaps="handled".
3.2.0release notes
Fixes manualActivation failing to block gesture activation on macOS.
2.33.0, 3.2.0release notes release notes
Prevents minDistance from being reset by partial configuration updates on Android.
3.2.0release notes
Fixes the behavior of the minVelocity props.
2.33.0, 3.2.0release notes release notes
Fixes Pan activation criteria being ignored on macOS.
2.33.0, 3.2.0release notes release notes
Aligns pointerType behavior between native and JavaScript.
2.33.0, 3.2.0release notes release notes
Fixes handling of requestDisallowInterceptTouchEvent for v3 on Android.
3.2.0release notes
Passes empty callbacks to the UI when runOnJS is true.
3.2.0release notes
Corrects the Tap offset on Web.
3.2.0release notes
Corrects the calculation of timeDelta on Web.
3.2.0release notes
Prevents a fatal crash when a touch event is serialized without allTouches.
2.33.0, 3.2.0release notes release notes
Fixes touch events not being delivered on macOS.
2.33.0, 3.2.0release notes release notes
Orphaned touch events are no longer dispatched.
3.2.0release notes
Fixes iOS touch events not being delivered to VirtualDetector handlers.
3.2.0release notes
Continuous gestures attached through VirtualGestureDetector now recognize on iOS.
3.2.0release notes
Android buttons no longer delay the child pressed state.
3.1.0release notes
Prevents gestures from being detached from other detectors on Web.
3.1.0release notes
Ensures a gesture is not used across multiple detectors.
3.1.0release notes
RootHelper no longer blocks the JS responder.
3.1.0release notes
Fixes js responder cancelation in iOS modals.
2.33.0, 3.1.0release notes release notes
Fixes handling of keyboardShouldPersistTaps so taps persist as expected while the keyboard is shown.
3.1.0release notes
Fixes a crash when updating SharedValue.
3.1.0release notes
Fixes text being selected during gestures on Android.
2.33.0, 3.1.0release notes release notes
On Android, the detector now accounts for child transforms.
3.0.2release notes
Native GestureDetector now handles zIndex correctly.
3.0.2release notes
On iOS, the hooks API now cancels JS Responder as expected.
3.0.2release notes
Android now applies numberOfPointers config to the pointer requirement in LongPressGestureHandler.
2.32.0, 3.0.2release notes release notes
Fixes mouse interactions on Android.
2.33.0, 3.0.2release notes release notes
Hidden action containers no longer receive pointer events on Android and Web.
2.33.0, 3.0.2release notes release notes
Fixes a crash when Android Pressable is used with Reanimated animations.
3.0.1release notes
Fixes invalid react-native/../react-native resolution for aliases in pods.
2.32.0, 3.0.1release notes release notes
Gesture relations are fixed after freeze.
2.33.1, 3.0.1release notes release notes
Fixes Android hover events recording gestures other than HoverGestureHandler.
3.0.1release notes
Fixes the number of pointers reported on Android.
2.32.0, 3.0.1release notes release notes
react-native-gesture-handler adds support for React Native 0.86.
2.32.0, 3.0.1release notes release notes
Fixes an iOS build issue with React Native 0.87-nightly.
3.0.1release notes
Fixes an Android crash with RN Screens FormSheet.
3.0.1release notes
Improves TalkBack support on Android.
3.0.1release notes
Fixes a build error on tvOS.
2.31.1, 3.0.1release notes release notes
Fixes buttons that could not be pressed on tvOS.
3.0.1release notes
Fixes the wrong coordinate space on web.
3.0.1release notes
avgTouches is correctly exposed.
3.0.0release notes
The onUpdate callback is restored for Native gestures.
3.0.0release notes
Adds support for React Native 0.85.
2.31.1, 3.0.0release notes release notes
Gesture Handler adds support for React Native 0.84.
3.0.0release notes
Corrects Android Rotation handling and aligns it with iOS.
3.0.0release notes

react-native-gesture-handler 258 changes

Breaking changes 3

Removes opacity from Swipeable action panels.
2.33.0release notes
GestureDetector now throws when no gesture is passed.
2.30.0release notes
Incorrectly exposed ReanimatedSwipeable props are now hidden.
2.30.0release notes

Deprecations 1

The 2.x line supports React Native 0.87; newer React Native releases are supported in Gesture Handler 3.
2.33.0release notes

New APIs and options 2

Forwards the borderless and foreground options from android_ripple.
2.33.0release notes
Forwards the borderless and foreground options from android_ripple.
2.33.0release notes

Performance 1

Memoizes the Text component.
2.31.0release notes

Behavior and default changes 2

On Web, the wheel listener is passive and registered only for Pan.
2.33.1release notes
iOS distinguishes mouse and stylus input when hovering.
2.31.0release notes

Fixes and other changes 49

Android alpha traversal now uses the same gate as iOS.
2.33.1release notes
Android clears a pending HOVER_EXIT finish when the hover handler is reset.
2.33.1release notes
Android avoids a null pointer exception if a touch cancel callback finishes the handler mid-transition.
2.33.1release notes
Fixes gesture callback guarantees when a view is detached mid-gesture on iOS.
2.33.0release notes
Prevents a crash when a mount listener fires after GestureDetector unmounts.
2.33.0release notes
Updates Pressable props.
2.33.0release notes
Clears pending timers on unmount.
2.33.0release notes
Stops nested scrolling when a native handler's gesture ends on Android.
2.33.0release notes
Moves Tap cancelation to dispatch_after on iOS.
2.33.0release notes
Removes UIPointerInteraction from the view when the hover handler is unbound.
2.33.0release notes
Fixes mismatched coordinate space on iOS.
2.32.0release notes
Fixes handler retrieval on iOS.
2.32.0release notes
Discrete gestures on Android now trigger onFinalize correctly.
2.32.0release notes
Fixes the RNRenderer import for React Native 0.86 and later.
2.32.0release notes
Fixes duplicated testID values on iOS.
2.32.0release notes
Fixes Pinch on the web.
2.31.2release notes
Fixes TalkBack behavior on Android for Pressable.
2.31.2release notes
Worklets are no longer checked for when the Babel plugin was not used.
2.31.2release notes
Fixes TypeScript errors in Touchables.
2.31.1release notes
Android clears blocking relations when a gesture handler is dropped.
2.31.0release notes
iOS handles FullWindowOverlay as the native root.
2.31.0release notes
Fixes GestureDetector becoming unresponsive after a display:none toggle in the New Architecture.
2.31.0release notes
Fixes compilation of RNGestureHandlerModule with Kotlin 2.3.
2.31.0release notes
Fixes a missing onFinalize callback in the Tap gesture on iOS.
2.31.0release notes
Android now checks all pointers in move events.
2.31.0release notes
Fixes the incorrect pointerType in the iOS Hover gesture.
2.31.0release notes
Handles pointerEvents for Pressable on iOS and Android.
2.31.0release notes
Guards +load with an #ifdef for RCT_DYNAMIC_FRAMEWORKS.
2.31.0release notes
Fixed the React 19 error caused by accessing element.ref on Web.
2.30.0release notes
Fixed experimental pointers breaking after a pan on Android.
2.30.0release notes
The GestureRef type now accepts null.
2.30.0release notes
Fixed a crash involving manual activation on iOS.
2.30.0release notes
On iOS, pan gestures blocked from activating now trigger onFinalize.
2.30.0release notes
Fixed onFinalize callbacks on iOS 26.
2.30.0release notes
Fixed the number of touches becoming 0 for pan gestures on Apple trackpads.
2.30.0release notes
Fixed press out behavior on Web.
2.30.0release notes
Added support for react-native 0.83.
2.30.0release notes
Fixed buttons not receiving onPress.
2.30.0release notes
Fixed a memory leak when ReanimatedSwipeable is closed programmatically.
2.30.0release notes
Fixed Android scroll actions being interpreted as touch.
2.30.0release notes
Fixes the ripple effect on Android.
2.29.1release notes
Fixes gestures not activating due to an outdated handler tag.
2.29.0release notes
Fixes gestures not ending properly on iOS 26.
2.29.0release notes
Fixes gestures on iOS 26.
2.29.0release notes
Excludes libfbjni.so.
2.29.0release notes
Prevents onPress from being called when Pressable is cancelled.
2.29.0release notes
Adds support for react-native 0.82.
2.29.0release notes
Fixes the grabbing delegate in setPressed.
2.29.0release notes
Ensures SwipeDirection is imported as a value in ReanimatedSwipeable.
2.29.0release notes