gorhom/react-native-bottom-sheet: what the Reanimated v3 sheet actually gives you

The gap this fills between a modal and a real sheet

React Native ships Modal, and it does one thing: it covers the screen. A bottom sheet has to do more. It has to sit at a partial height, snap between positions, stay draggable while a list inside it scrolls, and move out of the way when the keyboard appears. Doing that by hand means coordinating a gesture library, an animation library, and the scroll position of whatever is inside the sheet, all on the UI thread.

gorhom/react-native-bottom-sheet is a library that packages that coordination. The README describes it as "a performant interactive bottom sheet with fully configurable options" and lists the pieces it covers: gesture interactions and snapping animations, keyboard handling for iOS and Android, pull to refresh for scrollables, and integration with FlatList, SectionList, ScrollView and plain View. It also supports React Navigation integration, which matters because a sheet often needs to be opened from a screen and survive a navigation transition.

The audience is React Native application developers who already use Reanimated and Gesture Handler, or are willing to add them. It is not a general-purpose UI kit and it is not aimed at web-only projects, though the README states it supports React Native Web.

How the sheet is built: Reanimated, Gesture Handler and a portal

The library is written in TypeScript and its v5 line targets Reanimated v3 with Gesture Handler v2. That pairing is the mechanism. Gesture Handler owns the pan gesture on the sheet handle and the sheet body; Reanimated drives the animated position on the UI thread so the sheet keeps following the finger even when JavaScript is busy. The README frames the version split the same way: v5 is written with Reanimated v3 and Gesture Handler v2, v4 with Reanimated v2, and v2 with Reanimated v1 while remaining compatible with v2.

Presentation is split into two modes. The inline bottom sheet renders inside the current view tree. Bottom Sheet Modal is the other path, described in the README as a "Modal presentation view", which is what you reach for when the sheet should float above the rest of the app rather than be laid out inside a screen. The repository's runtime dependency list is short: @gorhom/portal at 1.0.14 and invariant. The portal package is what lets the modal form render outside its parent subtree.

The repository also carries a mock.js file that is published with the package. That is a deliberate affordance for Jest setups, since Reanimated and Gesture Handler normally need their own mocks in a test environment. The README does not document what mock.js replaces, so treat it as something to inspect in the repository rather than something the documentation explains.

Installing it and rendering a first sheet

The README does not list peer dependencies or an install command; it points to the documentation website at gorhom.dev/react-native-bottom-sheet for getting started. The package itself is published on npm as @gorhom/bottom-sheet, and the package.json shows the entry points: main is lib/commonjs/index, module is lib/module/index, types is lib/typescript/index.d.ts, and the react-native field points at src/index.ts. Because Reanimated and Gesture Handler are the animation and gesture layers, they have to be present in the app before the sheet will work; the README's versioning section is the place to confirm which Reanimated major each branch expects.

The repository ships an example/ directory with an App.tsx, an example/src/ tree and its own metro.config.js and babel.config.js. That is the most reliable place to see the two presentation modes wired up, and the root package.json exposes a script that installs the example app's dependencies.

yarn --cwd example

After that install completes, the example app is what you run to see a sheet on a device or simulator. Running the example is a more useful first step than guessing at peer versions, because the example's own package.json is the version combination the maintainer keeps working.

For a sheet inside a screen, the README points at the snapPoints and index props, and at Bottom Sheet Modal for the overlay form. The README does not print a full component example, so read the example app's App.tsx for the exact prop wiring rather than copying a snippet from a blog post; the repository's own example is the version that matches the installed library.

Where the sheet model breaks down

The versioning policy is the sharpest limitation. The README marks v4 and v2 as "not maintained" in plain text, and the author's own recommendation is to use v5. If your app is still on Reanimated v2 because of an older Expo SDK or a dependency that pins it, you are choosing between an unmaintained branch and an upgrade you may not control. That is a real cost, and the README does not offer a migration path between the branches beyond the changelog links.

The second constraint is architectural rather than a bug. A sheet that contains a scrollable has to decide who owns the gesture at any given moment: the sheet's pan handler or the list's scroll. The README lists support for FlatList, SectionList, ScrollView and View, and separately for FlashList, which tells you the library has explicit handling for this. It also tells you the handling is per-component. A custom scrollable that is not on that list is not covered by the same integration, and you would be reconciling the two gesture systems yourself.

Finally, the README is a landing page, not a manual. It links out for dynamic sizing, keyboard handling, pull to refresh, web support and React Navigation integration, and it does not document rollback behaviour, error states, or what happens when snap points change at runtime. Those answers live in the website and the source, not in the repository README.

How it differs from the Software Mansion sheet

The alternative that comes up most often in search is @swmansion/react-native-sheet, and the two take different positions on the same problem. The Software Mansion sheet is built to be used from React Navigation: you register it as a screen and navigate to it, so the sheet is a route and the navigation stack owns its lifecycle. gorhom's library treats the sheet as a component you render, with React Navigation integration listed as one supported case among several rather than the organising idea.

That difference decides a lot. If your sheets are destinations with their own params, deep links and back behaviour, the navigation-native model is a shorter path. If your sheets are transient UI attached to the screen you are already on, a component you mount is simpler, because you are not pushing and popping routes to show a picker. The gorhom library also exposes more of the sheet's internals as props: snap points, index, and the choice between inline rendering and Bottom Sheet Modal. The trade is that you assemble more of the behaviour yourself.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-05-09, which is the same day v5.2.14 was released. The two releases before it, v5.2.13 and v5.2.12, landed on 2026-04-30 and 2026-04-29. So the release cadence in the recent window is a patch stream on the v5 line, not a burst of new majors.

The upgrade cost is concentrated in the Reanimated major. Because v5 is written against Reanimated v3 and Gesture Handler v2, a Reanimated major bump in your app is the event that forces a decision here, not a minor version of this library. The repository keeps the branches separate precisely so that older Reanimated versions have a home, but the README labels those homes unmaintained. Budget the Reanimated upgrade, not the sheet upgrade.

The licence is MIT, declared in package.json and shipped as a LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification, and it requires the copyright notice and licence text to be preserved. That is a statement about the licence text, not legal advice for your situation.

Editorial conclusion

Adopt it if your app already runs Reanimated v3 and Gesture Handler v2 and you need scrollable, snapping sheets with keyboard handling on iOS and Android; the v5 branch is the one the author recommends and the one that receives releases. Do not adopt it if you are pinned to Reanimated v2 or v1 and cannot move, because the v4 and v2 branches are marked not maintained. Before wiring it into a screen, verify two things: that your project resolves the Reanimated v3 version the master branch expects, and that the presentation mode you pick (inline sheet versus Bottom Sheet Modal) matches where you want the sheet to sit in the navigation tree.

Frequently asked questions

Official sources

1. gorhom/react-native-bottom-sheet on GitHub
2. License: MIT
3. Project website
4. README
5. Releases