Skip to main content

Getting Started

Installation​

yarn add react-native-bottom-sheet-stack

Core Peer Dependencies​

yarn add react-native-reanimated react-native-safe-area-context react-native-teleport zustand

Adapter-Specific Dependencies​

Install only the dependencies for the adapter(s) you plan to use:

# For GorhomSheetAdapter (default bottom sheet adapter)
yarn add @gorhom/bottom-sheet react-native-gesture-handler

# For ModalAdapter — no extra dependencies (uses React Native's built-in Modal)

# For ReactNativeModalAdapter
yarn add react-native-modal

# For ActionsSheetAdapter
yarn add react-native-actions-sheet

tip

All adapter dependencies are optional. Only install what you use. Adapters with 3rd-party dependencies are shipped as separate subpath exports — importing the main package never triggers Metro resolution errors for uninstalled libraries.

Setup​

1. Setup Provider and Host​

Wrap your app with BottomSheetManagerProvider and add BottomSheetHost:

import {
  BottomSheetManagerProvider,
  BottomSheetHost,
  BottomSheetScaleView,
} from 'react-native-bottom-sheet-stack';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';

export default function App() {
  return (
    <SafeAreaProvider>
      <GestureHandlerRootView style={{ flex: 1 }}>
        <BottomSheetManagerProvider id="default">
          <BottomSheetScaleView>
            <YourAppContent />
          </BottomSheetScaleView>
          <BottomSheetHost />
        </BottomSheetManagerProvider>
      </GestureHandlerRootView>
    </SafeAreaProvider>
  );
}
Important

BottomSheetHost must be outside of BottomSheetScaleView. If you wrap BottomSheetHost inside BottomSheetScaleView, the bottom sheets themselves will also scale, which is not the desired behavior.

2. Create a Bottom Sheet Component​

Use GorhomSheetAdapter from the gorhom subpath instead of BottomSheet from @gorhom/bottom-sheet:

import { forwardRef } from 'react';
import { View, Text, Button } from 'react-native';
import { BottomSheetView } from '@gorhom/bottom-sheet';
import { useBottomSheetContext } from 'react-native-bottom-sheet-stack';
import { GorhomSheetAdapter } from 'react-native-bottom-sheet-stack/gorhom';

const MySheet = forwardRef((props, ref) => {
  const { close } = useBottomSheetContext();

  return (
    <GorhomSheetAdapter ref={ref} snapPoints={['50%']}>
      <BottomSheetView>
        <View style={{ padding: 20 }}>
          <Text>Hello from Bottom Sheet!</Text>
          <Button title="Close" onPress={close} />
        </View>
      </BottomSheetView>
    </GorhomSheetAdapter>
  );
});

3. Open Bottom Sheets​

import { useBottomSheetManager } from 'react-native-bottom-sheet-stack';

function MyComponent() {
  const { open } = useBottomSheetManager();

  const handleOpen = () => {
    open(<MySheet />, {
      mode: 'push', // 'push' | 'switch' | 'replace'
      scaleBackground: true,
    });
  };

  return <Button title="Open Sheet" onPress={handleOpen} />;
}