@mustmove/overlay-kit-rn

React Native overlay management library for modals and bottom sheets.

Installation

npm install @mustmove/overlay-kit-rn

Peer Dependencies

This library requires the following peer dependencies:

npm install react-native-reanimated react-native-gesture-handler @gorhom/bottom-sheet react-native-worklets

Quick Start

import { overlay, OverlayProvider } from '@mustmove/overlay-kit-rn';

// 1. Wrap your app with OverlayProvider
function App() {
  return (
    <OverlayProvider>
      <YourAppContent />
    </OverlayProvider>
  );
}

// 2. Create your modal component
const MyModal = ({ close }) => (
  <View>
    <Text>Hello Modal!</Text>
    <Button title="Close" onPress={close} />
  </View>
);

// 3. Open the modal
const openModal = () => {
  overlay.open(MyModal, {
    overlayType: 'modal',
    modalType: 'center',
  });
};

Features

• ✅ Pure React Native Modal (no third-party modal dependency)
• ✅ Bottom Sheet with @gorhom/bottom-sheet
• ✅ Multiple overlay types (modal, bottomSheet, overlay)
• ✅ Async modal support
• ✅ Nested modals
• ✅ TypeScript support
• ✅ Keyboard handling for bottom sheets

API

overlay.open(Component, options)

Opens an overlay with the specified component.

overlay.open(YourComponent, {
  overlayType: 'modal' | 'bottomSheet' | 'overlay',
  // Modal specific options
  modalType: 'center' | 'bottom' | 'top' | 'left' | 'right',
  backdropOpacity: 0.5,
  animationType: 'slideInUp' | 'slideInDown' | 'bounceIn' | 'fadeIn',
  // Bottom sheet specific options
  snapPoints: ['25%', '50%', '90%'],
  enablePanDownToClose: true,
});

overlay.openAsync(Component, options)

Opens an overlay and returns a promise that resolves with the result.

const result = await overlay.openAsync(AsyncComponent, {
  overlayType: 'modal',
});

Component Props

Your overlay components receive these props:

interface OverlayComponentProps {
  close: (result?: any) => void;
}

License

MIT