Skip to content

Gesture Handler 3.0 brings a hook-based API and drops the legacy architecture

updated

Software Mansion has released Gesture Handler 3, a major version of the gesture library that targets the New Architecture exclusively, introduces a hook-based API compatible with React Compiler, and reworks its Reanimated integration.

A hook-based API

The most notable change is a new API in which gestures are managed entirely through hooks, while components only attach them to the right views. Previously, the gesture lifecycle was fully handled by the component the gesture was attached to. The new design is compatible with React Compiler.

Existing users will find the API familiar, though some callbacks are renamed to better match the gesture state flow: onStart becomes onActivate, and onEnd becomes onDeactivate. The project's migration guide lists the most important changes.

Legacy Architecture support removed

Gesture Handler has supported the New Architecture since 2.3.0, but version 3 no longer supports the legacy architecture. According to the team, maintaining both held back new features. Dropping it enabled several internal changes:

  • Gestures can be attached to Text components and inline fragments.
  • The StateManager, previously limited to certain callbacks, is now available on both the JavaScript and main threads.
  • The button implementation has been rewritten.
  • The new API supports React Native's built-in Animated API.
  • A new cancelsJSResponder prop lets gestures work alongside the JS Responder system.

Reanimated integration

Integration points with Reanimated have been overhauled for performance. Combined with the new API, this makes it possible to use SharedValues directly in gesture configuration, so gesture properties can change without re-renders. The post also notes the change benefits RNRepo, a repository of pre-built React Native artifacts, since it will be possible to build the projects independently of each other.

The new Touchable

Touchable is now the recommended way to build buttons. It replaces both the aging TouchableOpacity / TouchableNativeFeedback / TouchableHighlight family and the library's own RectButton / BorderlessButton / BaseButton. Press feedback, ripples and opacity are handled on the platform side, without re-renders or JS round-trips. All other buttons in the library except Pressable are now deprecated and slated for removal in a future major version.

Benchmarks from release builds rendering 200 buttons per screen (20 cold mounts each) put Touchable at a mean paint time of 1231.36 ms on an OPPO A16 and 193.65 ms on a Pixel 7a. That compares with 1552.10 ms and 222.06 ms for the old RectButton, and 943.21 ms and 188.16 ms for React Native's own Pressable. Relative to Pressable, Touchable costs 1.31× (mean) on the OPPO A16 and 1.03× on the Pixel 7a, with the gap versus the old buttons larger on lower-end hardware.

Upgrading

All previous APIs remain available, so upgrading should mostly involve installing the new version and handling a few renames per the migration guide. Adoption of the hooks API can happen gradually, component by component or screen by screen. One caveat: the hooks API is not cross-compatible with the older APIs, so gestures that need relations such as simultaneous recognition must all use the hooks API. For teams using LLM agents, Software Mansion also offers a migration skill to assist the transition.

Source: swmansion.com