Skip to content

Gesture Handler 2.0 introduces a new gesture API

updated

Software Mansion has released Gesture Handler 2.0, a major update to the library that recognizes gestures such as pinch, rotation and pan using each platform's native touch system. The release introduces a new API designed from scratch, while keeping every version 1 API unchanged so existing apps can upgrade without rewriting gesture code.

A single detector for all gestures

Previously, tracking several concurrent gestures on one view (for example pan, pinch and rotation on an image) meant nesting multiple gesture-specific components, often mixed with React Native Views. Version 2.0 takes a different approach, with a GestureDetector component that can recognize every gesture type.

Gestures are now created through the Gesture object, configured with a builder-like pattern, and passed to the detector. GestureDetector also no longer has to wrap an actual React Native View; any composite component can sit directly beneath it, which makes it easier to move gesture logic into separate files.

Composing gestures

Instead of wiring multiple handlers together with refs, the Gesture object offers composition methods:

  • Simultaneous – all gestures can be active at once.
  • Race – the first gesture to activate cancels the others.
  • Exclusive – gestures are prioritized in order; each one can activate only if the previous one fails.

Reanimated 2 integration

When Reanimated 2 is installed, callbacks assigned to gesture events are automatically treated as worklets, and GestureDetector defaults to using them for synchronous event delivery. The trade-off is that the new API does not work with Reanimated 1 or React Native's Animated Events. Projects relying on those can continue to use the old Gesture Handler API until they migrate. According to the authors, one of the main reasons for the choice is that worklets allow synchronous communication with native code.

Touch events and Manual Gesture

The most important feature, according to the authors, is a new touch event type that tracks individual finger positions and lets a gesture's callback decide when it should activate or fail. Combined with the new Manual Gesture, this allows nearly any custom recognition logic, such as detecting drawn shapes or activating a pinch only when the midpoint between fingers falls within a specific area. Built-in gestures also gain the ability to control activation and failure programmatically from touch event callbacks, rather than relying solely on configuration options. Manual Gesture requires Reanimated 2.3 or newer.

Compatibility with the old API

The version 1 API is not being removed, and it is cross-compatible with the 2.0 API, including defining interactions such as running gestures simultaneously or waiting for others. Development will focus on the new API, but apps that stay on the old one can still upgrade and receive core fixes and improvements in future 2.x releases.

Why it matters

For React Native developers, Gesture Handler 2.0 reduces the nesting and ref wiring needed for multi-gesture interactions, and gives fine-grained control over gesture recognition through touch events. Because version 1 APIs remain intact, teams can upgrade now and adopt the new API incrementally. Those still on Reanimated 1 or Animated Events should keep in mind that the new API does not work with them.

The release was developed by Software Mansion and Shopify.

Source: swmansion.com