React Native Gesture Handler: UI thread gestures, and two major lines at once
Declarative API exposing platform native touch and gesture system to React Native.
At a glance
- What is it?
- A declarative API over the platform's native touch and gesture system, where gestures are recognized and tracked in the UI thread instead of the JS responder system. Version 3 requires react-native 0.82, and the version 2 line was still publishing days before this was written.
- Who is it for?
- Adopt React Native Gesture Handler when touch behaviour has to stay predictable under load, and pick your major line deliberately: version 3 raises the react-native floor to 0.82, while version 2 is the line with the long compatibility table back to react-native 0.63 and it is still receiving releases.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- software-mansion/react-native-gesture-handler6,805 ★ · +17
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| software-mansion/react-native-gesture-handler | 6.8k | 6.8k |
17 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Gestures leave the JS responder system for the UI thread
The architectural claim in this library is a single sentence: with it, gestures are no longer controlled by the JS responder system, but are instead recognized and tracked in the UI thread. Everything else in the description follows from that move. The package is a declarative API exposing the platform's native touch and gesture system to React Native, so a gesture is described rather than polled, and the recognition work happens where the native gesture recognizers live instead of in the JavaScript thread.
That relocation is what the README says makes touch interactions and gesture tracking dependable and deterministic, and it is also the entire value proposition: the library is not adding a new gesture vocabulary, it is changing which thread decides whether a finger down became a swipe. For an application whose gestures currently fight the JS responder system, that is the change worth measuring, and it is the reason the package is described as native driven rather than as a convenience wrapper.
The README has no install command for the library, the example does
Installation is deliberately absent from this repository's README, which points at the getting started section of the documentation site for the detailed instructions. What the README does give you is the fastest way to see the API work: clone the repo, move to the example folder, and run
yarn installAfter that, yarn start launches the metro bundler, and yarn android or yarn ios runs the example app on whichever platform you picked. One hardware requirement is stated plainly: you need an Android or iOS device or emulator connected. That is the whole procedure, three commands and a device, which makes the example project a better first check than installing the library into an application you care about.
Version 2 and version 3 both published inside three days
The release list is the first thing to read, because this project is maintaining two major lines at once. Version 3.4.0 and version 2.33.1 were both published on 2026-10-16, with 2.33.0 arriving earlier on 2026-09-14. The repository's most recent push is dated 2026-11-02 and it is not archived, so both lines are being touched rather than one being frozen.
That means the choice between 2.x and 3.x is a decision about your react-native version first and about features second, and it has consequences for how long you can wait before migrating. The 2.x line carries the long compatibility table, while 3.x has a single floor and delegates the rest to a table on the documentation site. Neither line is presented as deprecated, so picking the wrong one leaves you maintaining a dependency you will have to move later.
Gesture Handler 3 sets a floor of react-native 0.82
Support is stated twice, and the newer line has a stricter rule. The library supports the three latest minor releases of react-native. Then, under a callout marked important, comes the version 3 requirement: the minimal supported react-native version for Gesture Handler 3 is 0.82. The compatibility table for version 3 is not in the README at all, it is linked from the fundamentals installation page of the docs.
The version 2 table, by contrast, is printed in full, from 2.32.0 requiring react-native 0.84.0, through 2.28.0 for 0.79.0, 2.25.0 for 0.76.0, 2.21.0 for 0.74.0, 2.16.0 for 0.68.0, and down to 2.0.0 for 0.63.0. Below that floor the README offers one more option: it may be possible to use newer versions of the library on react-native 0.59 or older by reverse Jetifying, with a link to the Jetifier documentation. That is the whole compatibility story, and one line of it is guesswork the project itself hedges.
postinstall runs a full build, so a repo install is not a quick one
The root package.json names itself react-native-gesture-handler-monorepo, sets version 0.0.0 and marks itself private, so nothing here is the package you install into an application. It is a Yarn workspaces monorepo, and the postinstall script runs yarn build, which means installing the repository triggers a build of every workspace before the install finishes. That build first runs husky install, then a yarn workspaces foreach pass across all workspaces in parallel with topological dev ordering.
The same fan out shape is used for ts-check, lint-js and format-js, so every quality task in this repository is a workspace sweep rather than a single command. The clean script goes further: after sweeping the workspaces it removes node_modules and yarn.lock outright, which is a heavier reset than deleting a build directory and worth knowing before you run it on a checkout that has local changes you have not committed.
Four example workspaces are declared, the README explains two
The workspace list names four apps: apps/basic-example, apps/expo-example, apps/macos-example and apps/common-app, plus the library itself at packages/react-native-gesture-handler. The example coverage is therefore wider than the instructions suggest, because an Expo example and a macOS example both have a workspace entry.
The README only tells you how to run two of them. yarn android and yarn ios are the documented commands, and the connected device requirement is an Android or iOS device or emulator. There is a second, smaller mismatch worth flagging: the README says to go to the example folder, while the workspaces are declared under apps. Anyone scripting a first run will have to resolve that naming difference themselves.
Yarn 4.13.0, a checked-in .yarn directory, one patched dependency
The build tooling is pinned rather than left to defaults. packageManager is set to [email protected], a .yarn directory is checked in at the top level, and .yarnrc.yml sits beside it. A .nvmrc is present as well, though the version it pins is not stated in the repository files. Hooks are wired through a .husky directory with a .lintstagedrc.json, and native code carries its own .clang-format.
The top level also carries a git-blame-ignore-revs file, so at least one mass reformat is excluded from blame history.
Installation and the API reference both live on a separate docs site
The boundary of this README is easy to state: it names the library, describes the UI thread change, links the documentation site twice, and explains how to run the example. Everything else is delegated. Detailed installation steps are on the getting started page. The compatibility table for version 3 is on the fundamentals installation page. Questions about the library go to the Software Mansion community Discord, which the README points at for Gesture Handler and their other libraries.
What is absent inside the repository is as notable as what is there. The top level listing carries no changelog file, so release history lives on the releases page rather than in the tree, and there is no contributing guide next to the agent instruction files AGENTS.md and CLAUDE.md. The project is created by Software Mansion, a software agency since 2012 that describes itself as a Core React Native Contributor, and the MIT license covers the library itself.
Editorial conclusion
Adopt React Native Gesture Handler when touch behaviour has to stay predictable under load, and pick your major line deliberately: version 3 raises the react-native floor to 0.82, while version 2 is the line with the long compatibility table back to react-native 0.63 and it is still receiving releases. Do not expect the README to install the library for you, since the detailed instructions live on a separate docs site, and plan to read that page before you start, because the compatibility table and the getting started steps are the two pieces of information this repository does not carry.
Frequently asked questions
What does React Native Gesture Handler do?
It provides native driven gesture management APIs for React Native. Gestures are no longer controlled by the JS responder system, but are recognized and tracked in the UI thread, which the README says makes touch interactions and gesture tracking dependable and deterministic.
How do I install React Native Gesture Handler?
The README keeps installation out of itself and sends you to the getting started section of the documentation site. What it documents is the example app: clone the repo, go to the example folder, run yarn install, then yarn start for the metro bundler and yarn android or yarn ios, with a device or emulator connected.
How do I use React Native Gesture Handler?
You describe gestures through a declarative API that exposes the platform's native touch and gesture system, and the library recognizes and tracks them in the UI thread. Before wiring it into an application, note that the README says to go to the example folder while the root package.json declares the example workspaces under apps.
What is an alternative to React Native Gesture Handler?
The README names no competing library. It does name Software Mansion, which created Gesture Handler, has worked as a software agency since 2012 and describes itself as a Core React Native Contributor, plus a community Discord for questions about Gesture Handler and their other libraries.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.
- This Week In React #302 : Next.js, React Router, DevTools, Security | RN 0.88, Expo 58, Navigation | TypeScript, PHP, CrUXdev.to · Oct 23, 2026 · 2 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/software-mansion-react-native-gesture-handler)Star history chart for your README
[](https://hysenlabs.com/projects/software-mansion-react-native-gesture-handler)Was this useful?