Introducing Gesture Handler 3.0: Hook-Based API, Deeper Rea…

Meet Gesture Handler 3. This release brings your favorite gesture handling library up to speed in the new world, where the New Architecture is the Architecture, manual memoization is quickly becoming a relic of the past, thanks to the React Compiler, and interactions are more beautiful and more performant than ever, thanks to Reanimated 4.

New API based on hooks

To adapt to today’s environment, we had to make some changes, the most notable of which is the new hook-based API, which is compatible with React Compiler. This introduces a conceptual shift compared to previous implementations, where the gesture lifecycle was fully managed by the component it was attached to. In the new API, gestures are managed entirely using hooks, and components are responsible only for attaching them to the correct views.

If you have been using Gesture Handler so far, the new API will look familiar, but with some significant changes. The most noticeable ones are the renamed callbacks — onStart becomes onActivate, and onEnd becomes onDeactivate. The new names align more closely with the gesture state flow.

Side-by-side code example comparing a Gesture.Tap configuration with the new useTapGesture hook API

You can see the most important changes in the updated migration guide in our documentation.

Saying farewell to the legacy Architecture

Gesture Handler has supported the New Architecture since version 2.3.0. Keeping support for both the new and the legacy architectures proved difficult at times, and prevented us from utilizing the new features. Since the New Architecture has become the only architecture, Gesture Handler 3 will no longer support the legacy architecture.

This shift enabled us to make significant internal changes, unlocking previously unavailable capabilities:

You can now effortlessly attach gestures to Text components and inline fragments.
The StateManager, previously only available in select callbacks, is now generally available on the JavaScript and main threads.
The button implementation has been completely revamped.
The new API comes with support for React Native’s built-in Animated API.
New cancelsJSResponder prop that allows gestures to work alongside JS Responder.

…and there are many more enhancements on the horizon.

Updated Reanimated integration

We have also overhauled our integration points with Reanimated, making them even more performant. In combination with the new API, this enabled us to implement a long-requested feature — using SharedValues directly in the gesture config. This, finally, allows for changing the gesture properties with no re-renders.

Code example using useSharedValue and useTapGesture with numberOfTaps bound to a shared value

The improved integration will also benefit projects like RNRepo — a repository for React Native pre-built artifacts. Now, it will be possible to build the projects independently of each other.

Meet the new Touchable

Touchable is the new recommended way to build buttons in Gesture Handler 3 – a single, performant replacement for both the aging TouchableOpacity / TouchableNativeFeedback / TouchableHighlight family and our own RectButton / BorderlessButton / BaseButton. Touchable comes with built-in interactions - press feedback, ripples, opacity - driven entirely on the platform side. No re-renders, no JS round-trips, just native responsiveness out of the box. With this release, all of those - every other button in the library besides Pressable – are deprecated and will be removed in a future major version.

Numbers below are from release builds rendering 200 buttons per screen, 20 cold mounts each.

Paint time side-by-side (ms) — mean and median

Absolute cost: mean and median

Variant	OPPO A16 mean	OPPO A16 median	Pixel 7a mean	Pixel 7a median
`Touchable`	1231.36	1232.45	193.65	193.43
`Pressable`	943.21	999.29	188.16	185.95
`GHPressable`	1604.51	1600.42	257.76	254.41
`RectButton`	1552.10	1537.77	222.06	221.43

Relative cost vs. Pressable: mean and median

Variant	OPPO A16 mean	OPPO A16 median	Pixel 7a mean	Pixel 7a median
`Touchable`	1.31×	1.23×	1.03×	1.04×
`Pressable`	1.00×	1.00×	1.00×	1.00×
`GHPressable`	1.70×	1.60×	1.37×	1.37×
`RectButton`	1.65×	1.54×	1.18×	1.19×

As the tables above show, it's meaningfully cheaper than the buttons it replaces, with the gap widening on lower-end devices. There is still room to grow, and we will continue working on improvements in future releases.

Everything is still there

We are aware that adopting new things isn’t easy. In order to make the switch as simple as possible, we decided to keep all APIs available in the previous versions. This means that upgrading to Gesture Handler 3 should be as simple as installing the new version and checking the migration guide to adapt to a few name changes.

Adopting the new API itself can be done gradually — component by component or screen by screen. The only caveat is that the hooks API is not cross-compatible with the previous ones. To set up relations, like simultaneous, between the gestures, all of them will need to use the hooks API.

If you can use LLM Agents in your codebase, you can also try our migration skill, which should make the adoption even easier.

Thanks to Shopify

As always, we at Software Mansion would like to thank Shopify for their continued support of our open-source projects and trust throughout the years.

We’re Software Mansion: multimedia experts, AI explorers, React Native core contributors, community builders, and software development consultants.