A react-native component for displaying a modal on iOS

react-native-ios-modal

A react-native component for displaying a modal on iOS by natively wrapping a react-native view inside a UIViewController and presenting it.

• Since this is just using a UIViewController, this component also supports setting theUIModalPresentationStyle and UIModalTransitionStyle.
• Supports setting isModalInPresentation and separately disabling the native swipe down gesture when the modal is using pageSheet modalPresentationStyle.
• You can use ModalView anywhere in your app and present a view modally either programmatically via a ref or automatically when a ModalView is mounted/unmounted.
• Support for several modal events, multiple modals, and having a transparent background or a blurred background using UIBlurEffect.

Motivation

• You can use this, but it's iOS only (so you have to use a different modal component on android, like the built-in react-native component).
• I just really liked the native iOS 13 pageSheet modal behavior, and iOS also automatically handles the modal dismiss gesture when using a scrollview.
• So this component exist to tap into native iOS modal behaviour.

1. Installation

# install via NPM
npm install react-native-ios-modal

# or install via yarn
yarn add react-native-ios-modal

# then run pod install (uses autolinking)
cd ios && pod install

1.1 Installation Notes

• This library uses autolinking: tested and runs on RN version 0.60+ (Specific versions tested includes: 0.60, 0.62.2, and 0.63.3.)

• This library is written in swift. If you are having trouble building your app after installing this library, try adding an empty swift file.

1. Open up your ios/project.xcworkspace project
2. On the project navigator panel, right click on your project (or a folder/group) and select "New File..." option
3. In the popup/sheet, select swift click next
4. In the "Save As" popup/sheet, rename the file if you want to and click create
5. If Xcode asks you to create a "Objective-C Bridging Header", choose yes

2. Usage

Please check out the examples directory for more on how to use it.

// import the library
import { ModalView } from 'react-native-ios-modal';

// and use it like this
<ModalView ref={r => this.modalRef = r}>
  <Text> Hello World </Text>
<ModalView/>
<TouchableOpacity onPress={() => {
  this.modalRef.setVisibility(true);
}}>
  <Text> Open Modal </Text>
</TouchableOpacity>

3. Documentation

3.1 ModalView Component Props

3.1.1 Props: Flags

3.1.2 Props: Strings

3.1.3 Props: Modal Events

3.1.3 Props: Misc

3.1.4 Props: Modal Functions

3.2 ModalViewModule

A NativeModule that's a collection of functions to programmatically control a ModalView

• Import the module: import { ModalViewModule } from 'react-native-ios-modal'
• Example Usage: ModalViewModule.dismissAllModals(true)

3.3 Enum Values

3.3.1 Enum: UIBlurEffectStyles

Enum values that you can pass to the ModalView modalBGBlurEffectStyle prop. More detailed description are available in the Apple Developer Docs

• Import the enum like this: import { UIBlurEffectStyles } from 'react-native-ios-modal'
• And use the enum in the ModalView modalBGBlurEffectStyle prop like this: modalBGBlurEffectStyle={UIBlurEffectStyles.systemMaterial}
• Or if you prefer, just pass in a string value directly like this: modalBGBlurEffectStyle={'systemMaterial'}
• Here's an example component that cycles through all the available blur effect styles.

• Adaptable Styles — Changes based on the current system appearance. Requires iOS 13 and above.

1. systemUltraThinMaterial
2. systemThinMaterial
3. systemMaterial
4. systemThickMaterial
5. systemChromeMaterial

• Light Styles — Blur styles that are tinted white/light. Meant to be used for system light appearance. Requires iOS 13 and above.

1. systemMaterialLight
2. systemThinMaterialLight
3. systemUltraThinMaterialLight
4. systemThickMaterialLight
5. systemChromeMaterialLight

• Dark Styles — Blur styles that are tinted black/dark. Meant to be used for system dark appearance. Requires iOS 13 and above.

1. systemChromeMaterialDark
2. systemMaterialDark
3. systemThickMaterialDark
4. systemThinMaterialDark
5. systemUltraThinMaterialDark

• Regular Styles — Blur styles that were originally added in iOS 10.

1. regular
2. prominent

• Light/Dark Styles — Blur styles that were originally added in iOS 8.

3. light
4. extraLight
5. dark

3.3.2 Enum: UIModalPresentationStyles

Enum values that you can pass to the ModalView modalPresentationStyle prop. More detailed description are available in the Apple Developer Docs

• Import the enum like this: import { UIModalPresentationStyles } from 'react-native-ios-modal'
• And use the enum in the ModalView modalPresentationStyle prop like this: modalPresentationStyle={UIModalPresentationStyles.fullScreen}
• Or if you prefer, just pass in a string value directly like this: modalPresentationStyle={'fullScreen'}
• Here's an example component that cycles through all the available blur effect styles.

• Supported Presentation Styles

1. automatic — Requires iOS 13 to work. The default presentation style for iOS 13 and above.
2. fullScreen — Present fullscreen but with an opaque background. The default presentation style on iOS 12 and below.
3. overFullScreen — Present fullscreen but with a transparent background.
4. pageSheet — The presentation style used on iPhones running iOS 13. Present a modal that can be dismissed via a swipe gesture.
5. formSheet — The presentation style used on iPads. Same as pageSheet when on iPhone.

• Not Supported

1. none
2. currentContext
3. custom
4. overCurrentContext
5. popover
6. blurOverFullScreen

3.3.3 Enum: UIModalTransitionStyles

Enum values that you can pass to the ModalView modalTransitionStyle prop. More detailed description are available in the Apple Developer Docs

• Import the enum like this: import { UIModalTransitionStyles } from 'react-native-ios-modal'
• And use the enum in the ModalView modalTransitionStyle prop like this: modalTransitionStyle={UIModalTransitionStyles.coverVertical}
• Or if you prefer, just pass in a string value directly like this: modalTransitionStyle={'coverVertical'}

• Supported Transition Styles

1. coverVertical
2. crossDissolve
3. flipHorizontal

• Not Supported

1. partialCurl

3.3.4 Enum: ModalEventKeys

Enum values that you can use in the ModalView EventEmitter instance. Use the enum values to add/remove a listener.

• Import the enum like this: import { ModalEventKeys } from 'react-native-ios-modal'
• And use the enum in the ModalView EventEmitter instance like this: modalEmitter.addListener(ModalEventKeys.onModalShow, this._handleOnModalShow)
• Or if you prefer, just pass in a string value directly like this: modalEmitter.addListener('onModalShow', this._handleOnModalShow)
• You can get a ref to a modal's EventEmitter like this: modalRef.getEmitterRef()

1. onModalBlur
2. onModalFocus
3. onModalShow
4. onModalDismiss
5. onModalDidDismiss
6. onModalWillDismiss
7. onModalAttemptDismiss

3.4 ModalContext

A context you can use inside the ModalView component.

• Import the context like this: import { ModalContext } from 'react-native-ios-modal'

3.5 withModalLifecycle HOC

A HOC function that wraps a component so you can listen to the modal events in that component. The wrapped component must be a child of ModalView i.e the component must be use inside the ModalView component. This is because the HOC uses the ModalContext to subscribe to the events of the ModalView. The HOC handles consuming the ModalContext and subscribing/unsubscribing to the modal's EventEmitter instance. Check out the example for more on how to use it.

• Import the HOC function like this: import { withModalLifecycle } from 'react-native-ios-modal'
• Wrap the component using the HOC function: export default withModalLifecycle(ModalContents);
• In the wrapped component, declare a member function with the name of the event that you want to use: onModalFocus({nativeEvent}){ ... }
• The name of the function must match any of the keys/strings defined in ModalEventKeys

3.6 Modal EventEmitter

• Each ModalView has an EventEmitter instance, so the first step to use it is to get a ref to the emitter.
  • If you have a reference to the ModalView, you can call modalRef.getEmitterRef() to get a ref to the emitter instance.
  • Or you can get a ref to the emitter instance via context: this.context.getEmitterRef() or const { getEmitterRef } = useContext(ModalContext)

• To subscribe to a modal event: modalEmitter.addListener('onModalBlur', this._handleOnModalBlur)
• To unsubscribe to a modal event: modalEmitter.removeListener('onModalBlur', this._handleOnModalBlur)
• The string of available events to subscribe to are in ModalEventKeys

3.7 Modal NativeEvent object

Example {nativeEvent} object that gets passed to all the modal events.

{
  "isInFocus": true,
  "isPresented": true,
  "modalLevel": 1,
  "modalLevelPrev": -1,
  "modalUUID": "DDADB792-3F85-4849-B669-AB734EC3B610",
  "target": 197
}

• isInFocus: bool — whether or not the modal is in focus
• isPresented: bool — whether or not the modal is visible or not
• modalLevel: int — indicates the modal level (ex: 1 means it's the first modal that's currently visible, etc.)
• modalLevelPrev: int — indicates the modal level (-1 means it's not currently visible)
• modalUUID: string — the modal's auto generated unique ID.

3.8 Constants

3.8.1 AvailableBlurEffectStyles Constant

An array of UIBlurEffectStyles strings you can use on a ModalView's modalBGBlurEffectStyle prop. The available blur effect styles are based on the iOS version the app is running on.

• Example: import { AvailableBlurEffectStyles } from 'react-native-ios-modal';
• On android, AvailableBlurEffectStyles will be empty.

3.8.2 AvailablePresentationStyles Constant

An array of UIModalPresentationStyles strings you can use on a ModalView's modalTransitionStyle prop. The available presentation styles are based on the iOS version the app is running on.

• Example: import { AvailablePresentationStyles } from 'react-native-ios-modal';
• On android, AvailablePresentationStyles will be empty.

4. Examples

Check out the examples directory for testing out the ModalView.

GitHub