react-native-bottom-sheet-modal-lite

A lightweight, spring-animated bottom sheet modal for React Native, powered by React Native Reanimated and React Native Gesture Handler.

Features

• Spring-based open, close, and snap-back animations
• Close by pressing the backdrop
• Close by dragging the top handle downward
• Keyboard avoidance support
• Configurable size, backdrop, corner radius, and dismissal thresholds
• TypeScript support
• Named and default exports

Requirements

• React >=18.2.0
• React Native >=0.72.0
• React Native Reanimated >=3.0.0 <5.0.0
• React Native Gesture Handler >=2.9.0 <4.0.0

Installation

npm install react-native-bottom-sheet-modal-lite react-native-reanimated react-native-gesture-handler

Complete the native setup required by the versions of React Native Reanimated and React Native Gesture Handler installed in your app.

For iOS, install CocoaPods after installing the dependencies:

cd ios
pod install
cd ..

App setup

Wrap your app root with GestureHandlerRootView:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <RootNavigator />
    </GestureHandlerRootView>
  );
}

The component also renders a GestureHandlerRootView inside its native modal so gestures work within the modal content.

Basic usage

import React, { useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import { BottomSheetModal } from 'react-native-bottom-sheet-modal-lite';

export default function ExampleScreen() {
  const [visible, setVisible] = useState(false);

  return (
    <View style={styles.screen}>
      <Button
        title="Open bottom sheet"
        onPress={() => setVisible(true)}
      />

      <BottomSheetModal
        visible={visible}
        onDismiss={() => setVisible(false)}
        height={300}
        backgroundColor="#FFFFFF"
      >
        <View style={styles.content}>
          <Text>Bottom sheet content</Text>
        </View>
      </BottomSheetModal>
    </View>
  );
}

const styles = StyleSheet.create({
  screen: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  content: {
    flex: 1,
    padding: 20,
  },
});

A default export is also available:

import BottomSheetModal from 'react-native-bottom-sheet-modal-lite';

The props type can be imported when needed:

import type { BottomSheetModalProps } from 'react-native-bottom-sheet-modal-lite';

Closing the sheet

When the user closes the sheet by pressing the backdrop, dragging the handle, or using the Android back button, onDismiss runs after the closing animation finishes.

Update your state inside onDismiss:

<BottomSheetModal
  visible={visible}
  onDismiss={() => setVisible(false)}
>
  {children}
</BottomSheetModal>

To close the sheet programmatically, set visible to false:

setVisible(false);

Keyboard configuration

The default keyboard behavior is:

• iOS: padding
• Android: height
• Vertical offset: 0

Override it when your app uses a custom header or keyboard layout:

<BottomSheetModal
  visible={visible}
  onDismiss={() => setVisible(false)}
  keyboardBehavior="padding"
  keyboardVerticalOffset={80}
>
  {children}
</BottomSheetModal>

Disable keyboard avoidance when it is not needed:

<BottomSheetModal
  visible={visible}
  onDismiss={() => setVisible(false)}
  keyboardAvoidingEnabled={false}
>
  {children}
</BottomSheetModal>

Custom styling

<BottomSheetModal
  visible={visible}
  onDismiss={() => setVisible(false)}
  height={420}
  backgroundColor="#FFFFFF"
  backdropColor="rgba(0, 0, 0, 0.65)"
  borderRadius={24}
  containerStyle={{ elevation: 10 }}
  dragHandleStyle={{ backgroundColor: '#E5E7EB' }}
  contentContainerStyle={{ paddingHorizontal: 20 }}
>
  {children}
</BottomSheetModal>

Props

| Prop | Type | Default | Description | | --- | --- | --- | --- | | visible | boolean | Required | Controls whether the native modal is visible. | | onDismiss | () => void | Required | Called after a user-triggered dismissal animation finishes. Set visible to false here. | | children | ReactNode | Required | Content rendered inside the sheet. | | height | number | 300 | Total visible height of the sheet, including the draggable top area. | | backgroundColor | string | transparent | Background color of the sheet container. | | backdropColor | string | rgba(0, 0, 0, 0.5) | Background color of the full-screen backdrop. | | closeOnBackdropPress | boolean | true | Allows pressing the backdrop to dismiss the sheet. | | enablePanDownToClose | boolean | true | Enables the downward pan gesture on the draggable top area. | | dragHandleHeight | number | 30 | Height of the draggable top area. | | extraHeight | number | 200 | Extra hidden height rendered below the screen during animation. | | borderRadius | number | 30 | Top-left and top-right corner radius. | | dismissThreshold | number | 0.5 | Portion of the sheet height that must be dragged before dismissal. Values are clamped between 0 and 1. | | dismissVelocity | number | 900 | Downward gesture velocity that triggers dismissal. | | keyboardBehavior | 'height' \| 'position' \| 'padding' | Platform default | Behavior passed to KeyboardAvoidingView. | | keyboardVerticalOffset | number | 0 | Vertical offset passed to KeyboardAvoidingView. | | keyboardAvoidingEnabled | boolean | true | Enables or disables KeyboardAvoidingView. | | containerStyle | StyleProp<ViewStyle> | — | Additional style for the animated sheet container. | | backdropStyle | StyleProp<ViewStyle> | — | Additional style for the backdrop. | | dragHandleStyle | StyleProp<ViewStyle> | — | Additional style for the draggable top area. | | contentContainerStyle | StyleProp<ViewStyle> | — | Additional style for the children container. | | testID | string | — | Test identifier applied to the animated sheet container. | | backdropAccessibilityLabel | string | Close bottom sheet | Accessibility label for the backdrop button. |

Notes

• The drag-to-close gesture begins only from the top draggable area.
• Negative height, dragHandleHeight, and extraHeight values are treated as 0.
• dismissThreshold is clamped between 0 and 1.
• The default sheet background is transparent. Set backgroundColor or provide your own styled child view when you need a solid sheet.