react-native-gesture-handler: native gestures for React Native, and when v3 forces an upgrade

The JS responder is the thing being replaced

React Native's built-in touch system routes gesture decisions through the JS responder. When the JS thread is busy, that pipeline stalls, and a drag can feel like it is being decided after the fact. react-native-gesture-handler takes a different route: the README states that gestures are "no longer controlled by the JS responder system, but instead are recognized and tracked in the UI thread." The project describes the result as smooth, dependable and deterministic, which is the whole pitch in one line.

The audience is React Native application developers, not library authors working on other platforms. The repository is a Yarn workspaces monorepo with the published package under packages/react-native-gesture-handler and runnable apps under apps/, including a basic example, an Expo example, a macOS example, and a shared common app. That layout says something about intent: the maintainers keep first-class example apps for several hosts rather than a single demo, which is what you would expect from a library whose behaviour differs between iOS, Android and macOS.

Two major lines, and the compatibility table is the real gate

The most consequential fact in the README is that Gesture Handler 2 and Gesture Handler 3 are both live. The repository shipped v2.33.0 on 2026-09-14 and v3.3.0 on 2026-09-11, with v3.2.1 before that on 2026-08-14. Two maintained majors means two upgrade stories, and the README handles them with separate tables rather than one merged matrix.

For Gesture Handler 3, the README states plainly that the minimal supported react-native version is 0.82, and points to a compatibility table in the docs under fundamentals/installation#requirements. For Gesture Handler 2 the table is in the README itself: 2.32.0+ needs react-native 0.84.0+, 2.28.0+ needs 0.79.0+, 2.26.0+ needs 0.78.0+, 2.25.0+ needs 0.76.0+, 2.24.0+ needs 0.75.0+, and the list continues down to 2.0.0+ on 0.63.0. The README also notes that the library supports the three latest minor releases of react-native.

Read those two facts together and a constraint appears that the README does not spell out: the newest v2 releases have a higher React Native floor than the v3 floor. Someone on React Native 0.82 or 0.83 cannot take 2.32.0+, and the README does not say which v2 release is the newest one that still works there. You would have to walk the table backwards to find a row that fits.

Installing it and getting one gesture onto the screen

The README does not carry installation steps. It says to check the getting started section of the documentation for detailed instructions, and links to docs.swmansion.com/react-native-gesture-handler/docs/#installation. Treat that page as the source of truth for your platform, because the native side differs between a bare React Native project and an Expo project, and the repository keeps a separate apps/expo-example precisely because that path is not identical.

What the README does give is a way to run the library's own example app without wiring it into your project. Clone the repository, go to the example folder and install:

yarn install

Then start the bundler and launch a platform. The README gives these three commands:

yarn start
yarn android
yarn ios

Run yarn android or yarn ios depending on the platform, and the README notes you will need an Android or iOS device or emulator connected. What you should see is the example app itself, which is the fastest way to judge whether the gesture feel matches what you want before you touch your own codebase.

For a real project, follow the docs installation page and then import from the package. The README does not publish a canonical code sample, so any snippet you copy from elsewhere should be checked against the API reference at docs.swmansion.com/react-native-gesture-handler/docs/ before you trust it.

Where the native-driven model becomes the wrong choice

The trade-off is structural. Recognising gestures on the UI thread means the native side owns the gesture lifecycle, and that puts a boundary between your gesture code and the rest of your React state. Work that has to happen on every frame of a drag cannot wait for JS, and work that has to read JS state cannot happen in the middle of a native gesture without a bridge crossing. If your interaction is simple enough that the responder system already feels fine, you are adding a native dependency and a compatibility obligation to solve a problem you do not have.

The version floor is the second failure mode, and it is the one that bites during upgrades. Because the library supports the three latest minor releases of react-native, an app that lags behind loses support as the library moves forward. The README's own reverse-Jetify note is a signal of how far this can go: it mentions that newer versions may be usable on React Native <= 0.59 by reverse Jetifying, and points to an external repository for that. That is a workaround, not a supported configuration.

Third, the README does not document a rollback path for the native installation, and it does not describe what happens to gesture behaviour when you remove the library from a project that already depends on it. If you are evaluating it, plan the removal before you plan the adoption.

What you would use instead, and how the approach differs

The obvious alternative is React Native's own responder system: TouchableOpacity, PanResponder, and the ScrollView touch handling that ships with the framework. The difference is not a feature list, it is where the decision is made. The responder system decides in JS, which means gesture recognition competes with your render work for the same thread. Gesture Handler decides natively on the UI thread and reports the outcome, which is why the README frames the benefit as determinism rather than as extra gesture types.

That framing also tells you when the alternative wins. If your app is mostly static screens with taps and short scrolls, the framework's responders are already native-backed for the common cases, and adding Gesture Handler buys you a version constraint you now have to track against every React Native upgrade. The library earns its place when gestures are continuous and stateful: drags, swipes, pinch, and interactions that must keep tracking while the rest of the app is busy.

A second alternative worth naming is doing nothing at all and staying on the version you have. The README's compatibility tables exist because that choice is legitimate. The cost is that you stop receiving fixes for the gesture layer, and the tables make the cost visible instead of hiding it.

Maintenance, releases and what the MIT licence does not cover

The repository is not archived, and the last push was on 2026-09-21, one day before this writing, with releases landing on 2026-09-14 and 2026-09-11. Development is current, and the release cadence shows two lines being maintained in parallel rather than one line plus a frozen predecessor.

The practical upgrade cost sits in the compatibility tables, not in the release notes. Because the published package lives in a monorepo under packages/react-native-gesture-handler, the version you install is decoupled from the repository's own version field, which is 0.0.0 and marked private. The monorepo runs on [email protected] with a postinstall hook that builds the workspaces, so anyone cloning the repository to work on the library itself is building it, not consuming it.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution with the licence and copyright notice retained. It provides no warranty, and it grants no patent rights. That is a description of the licence text, not legal advice; if your organisation has specific requirements around patent grants or indemnification, take it to counsel rather than to a README.

Editorial conclusion

Adopt it if you ship React Native apps where touch feedback has to survive a busy JS thread, and if your React Native version already sits at or above the floor your Gesture Handler line requires. Do not adopt it as a drop-in replacement for every TouchableOpacity in an app that is still on an older React Native release, because Gesture Handler 3 requires React Native 0.82 minimum and the v2 table ties 2.32.0+ to 0.84.0+. Before you commit, check your React Native version against the compatibility table, confirm which major line you are installing, and read the installation page rather than copying a snippet from a blog post.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. software-mansion/react-native-gesture-handler on GitHub