Gesture Handler 3.0 brings a hook-based API and drops the legacy architecture
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
Textcomponents 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
AnimatedAPI. - A new
cancelsJSResponderprop 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.
Links
Source: swmansion.com