react-native-keyboard-aware-modal

A smooth animated modal component for React Native that is keyboard-aware and can be used as a controller. Built with react-native-reanimated and react-native-gesture-handler for performant animations and gestures.

Features

• 🎹 Keyboard Aware - Automatically adjusts when keyboard appears/disappears
• 🎨 Smooth Animations - Customizable spring and timing animations
• 👆 Draggable - Drag to dismiss with snap points support
• 🎛️ Modal Controller - Context-based API for easy modal management
• 🎯 Flexible Usage - Use with ModalController or directly as a component
• 🎨 Highly Customizable - Custom headers, styles, animations, and more
• 📱 TypeScript Support - Full TypeScript definitions included
• ⚡ Performant - Built with Reanimated for 60fps animations

Installation

npm install react-native-keyboard-aware-modal

or

yarn add react-native-keyboard-aware-modal

Peer Dependencies

This library requires the following peer dependencies:

npm install react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-worklets

Important: Make sure to follow the setup instructions for:

• react-native-gesture-handler
• react-native-reanimated
• react-native-safe-area-context

Usage

Using ModalController (Recommended)

The ModalController provides a context-based API for managing modals throughout your app.

1. Wrap your app with ModalControllerProvider

import { ModalControllerProvider } from 'react-native-keyboard-aware-modal';

function App() {
  return (
    <ModalControllerProvider>
      {/* Your app content */}
    </ModalControllerProvider>
  );
}

2. Use the useModal hook to show modals

import { useModal } from 'react-native-keyboard-aware-modal';
import { View, Text, TouchableOpacity } from 'react-native';

function MyComponent() {
  const { showModal } = useModal();

  const openModal = () => {
    showModal(
      () => (
        <View style={{ padding: 20 }}>
          <Text>Hello from modal!</Text>
        </View>
      ),
      {
        // Optional configuration
        backgroundColor: 'white',
        borderRadius: 20,
        keyboardAware: true,
      }
    );
  };

  return (
    <TouchableOpacity onPress={openModal}>
      <Text>Open Modal</Text>
    </TouchableOpacity>
  );
}

Using KeyboardAwareModal Directly

You can also use KeyboardAwareModal directly without the controller context:

import { KeyboardAwareModal } from 'react-native-keyboard-aware-modal';
import { useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';

function MyComponent() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <Text>Open Modal</Text>
      </TouchableOpacity>

      <KeyboardAwareModal
        visible={visible}
        onClose={() => setVisible(false)}
        keyboardAware={true}
        backgroundColor="white"
        borderRadius={20}>
        <View style={{ padding: 20 }}>
          <Text>Hello from modal!</Text>
        </View>
      </KeyboardAwareModal>
    </>
  );
}

Examples

Check out the examples folder for comprehensive examples:

• BasicModalExample - Basic modal usage with different configurations
• CustomHeaderExample - Creating custom headers
• DraggableModalExample - Draggable modals with snap points
• AnimationCustomizationExample - Customizing animations
• KeyboardAwareExample - Keyboard-aware forms
• DirectModalExample - Direct component usage

To run the examples:

cd example
yarn install
yarn ios  # or yarn android

API Reference

ModalControllerProvider

Provider component that wraps your app to enable modal controller functionality.

<ModalControllerProvider>
  {children}
</ModalControllerProvider>

useModal Hook

Returns an object with showModal and hideModal functions.

const { showModal, hideModal } = useModal();

showModal(renderContent, config?)

• renderContent: A function that returns the modal content (ReactNode)
• config?: Optional ModalConfig object

hideModal()

Closes the currently visible modal.

KeyboardAwareModal Props

Prop	Type	Description	Default
visible	boolean	Controls modal visibility	required
onClose	() => void	Callback when modal should close	required
children	ReactNode	Modal content	required
headerView	ReactNode	Custom header component	undefined
snapPoints	number[]	Array of heights (0-1) where modal can snap	[0]
initialSnapIndex	number	Initial snap point index	0
dragHandle	boolean	Show drag handle indicator	false
dragHandleStyle	ViewStyle	Custom drag handle style	undefined
extraClosingThreshold	number	Extra pixels to drag before closing	40
draggable	boolean	Enable drag to dismiss	true
keyboardAware	boolean	Automatically adjust for keyboard	true
backgroundColor	string	Modal background color	'white'
backdropColor	string	Backdrop color	'rgba(0, 0, 0, 0.5)'
backdropOpacity	number	Backdrop opacity (0-1)	1
showBackdrop	boolean	Show backdrop overlay	true
roundedCorners	boolean	Round top corners	true
borderRadius	number	Border radius for top corners	20
openingAnimation	ModalAnimationConfig	Custom opening animation	undefined
closingAnimation	ModalAnimationConfig	Custom closing animation	undefined
backdropAnimation	BackdropAnimationConfig	Custom backdrop animation	undefined
mainContainerStyle	ViewStyle	Main container style	undefined
modalContentStyle	ViewStyle	Modal content wrapper style	undefined
headerStyle	ViewStyle	Header container style	undefined
contentStyle	ViewStyle	Content container style	undefined
contentContainerStyle	ViewStyle	ScrollView content container style	undefined
maxModalHeight	number	Maximum height for the modal content	undefined
layoutAnimation	LayoutAnimation	Custom layout animation for the modal container	LinearTransition.springify().damping(25).stiffness(120).duration(500)

ModalConfig

Configuration object for showModal:

interface ModalConfig {
  headerView?: ReactNode;
  snapPoints?: number[];
  initialSnapIndex?: number;
  dragHandle?: boolean;
  dragHandleStyle?: ViewStyle;
  extraClosingThreshold?: number;
  draggable?: boolean;
  keyboardAware?: boolean;
  backgroundColor?: string;
  backdropColor?: string;
  backdropOpacity?: number;
  showBackdrop?: boolean;
  roundedCorners?: boolean;
  borderRadius?: number;
  openingAnimation?: ModalAnimationConfig;
  closingAnimation?: ModalAnimationConfig;
  backdropAnimation?: BackdropAnimationConfig;
  mainContainerStyle?: ViewStyle;
  modalContentStyle?: ViewStyle;
  headerStyle?: ViewStyle;
  contentStyle?: ViewStyle;
  contentContainerStyle?: ViewStyle;
  maxModalHeight?: number;
  layoutAnimation?:  LayoutAnimation;
}

Animation Configuration

ModalAnimationConfig

interface ModalAnimationConfig {
  type?: 'spring' | 'timing';
  springConfig?: {
    damping?: number;
    stiffness?: number;
    mass?: number;
    overshootClamping?: boolean;
    restDisplacementThreshold?: number;
    restSpeedThreshold?: number;
    velocity?: number;
  };
  timingConfig?: {
    duration?: number;
    easing?: EasingFunction;
  };
}

BackdropAnimationConfig

interface BackdropAnimationConfig {
  duration?: number;
  easing?: EasingFunction;
}

Advanced Examples

Draggable Modal with Snap Points

showModal(
  () => (
    <View style={{ padding: 20 }}>
      <Text>Drag me up and down!</Text>
    </View>
  ),
  {
    snapPoints: [0.5, 0.75, 1], // 50%, 75%, 100% of screen height
    initialSnapIndex: 1, // Start at 100%
    dragHandle: true,
  }
);

Custom Animation

showModal(
  () => <View>...</View>,
  {
    openingAnimation: {
      type: 'spring',
      springConfig: {
        damping: 20,
        stiffness: 90,
      },
    },
    closingAnimation: {
      type: 'timing',
      timingConfig: {
        duration: 200,
      },
    },
  }
);

Custom Header

showModal(
  () => <View>...</View>,
  {
    headerView: (
      <View style={{ padding: 16, backgroundColor: '#f0f0f0' }}>
        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
          Custom Header
        </Text>
      </View>
    ),
  }
);

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

---

Made with create-react-native-library