React Native Bottom Sheet — Performant Interactive Bottom Sheets

Introduction

@gorhom/bottom-sheet provides a production-ready bottom sheet component that leverages Reanimated worklets for UI-thread animations and Gesture Handler for native touch tracking. It handles keyboard avoidance, dynamic content sizing, and scrollable content out of the box.

What React Native Bottom Sheet Does

• Renders a draggable sheet that snaps to configurable percentage or pixel-based snap points
• Handles keyboard appearance by adjusting sheet position automatically
• Supports scrollable content via BottomSheetScrollView, FlatList, and SectionList wrappers
• Provides a modal variant with backdrop dimming and press-to-dismiss
• Exposes imperative methods for programmatic open, close, and snap-to-index control

Architecture Overview

The component runs its gesture and animation logic entirely on the UI thread through Reanimated worklets. A PanGestureHandler tracks vertical drag gestures and updates a shared animated position value. Snap-point calculations happen in worklets, and the sheet interpolates its translateY transform each frame. Scrollable children coordinate with the gesture handler via a custom NativeViewGestureHandler to prevent scroll conflicts.

Self-Hosting & Configuration

• Requires react-native-reanimated (v2+) and react-native-gesture-handler as peer dependencies
• Wrap root component in GestureHandlerRootView for gesture recognition
• Set enablePanDownToClose for swipe-to-dismiss behavior
• Configure backgroundStyle and handleIndicatorStyle for visual customization
• Use onChange and onAnimate callbacks for tracking sheet state transitions

Key Features

• UI-thread-only animations deliver consistent 60 fps performance
• Dynamic sizing via enableDynamicSizing adjusts to content height automatically
• Built-in keyboard handling with configurable behavior (extend, interactive, fillParent)
• Footer component support for fixed-position action buttons
• Detached mode for floating sheets positioned anywhere on screen

Comparison with Similar Tools

• react-native-modal — general-purpose modal; bottom-sheet specializes in draggable panels
• reanimated-bottom-sheet (osdnk) — earlier implementation with fewer features and less maintenance
• react-native-raw-bottom-sheet — simpler API but no gesture-driven snapping or keyboard handling
• Native UISheetPresentationController — iOS-only; @gorhom/bottom-sheet works cross-platform

FAQ

Q: Can I use it without Reanimated? A: No. Reanimated is a required peer dependency for the worklet-based animation architecture.

Q: How do I use scrollable content inside the sheet? A: Replace ScrollView with BottomSheetScrollView (or BottomSheetFlatList) to coordinate scroll and drag gestures.

Q: Can I stack multiple bottom sheets? A: Yes. Each BottomSheet instance manages its own state and can be controlled independently.

Q: Does it support landscape orientation? A: Yes. Snap points and layout recalculate automatically on orientation changes.

Sources

• https://github.com/gorhom/react-native-bottom-sheet
• https://gorhom.dev/react-native-bottom-sheet/