Introducing Gesture Handler 3.0: Hook-Based API, Deeper Reanimated Integration & More

Meet the first beta release of 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.

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.

…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.

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.

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.