A react-native component for displaying a modal on iOS by natively wrapping a react-native view inside a UIViewController
and presenting it.
UIViewController
, this component also supports setting theUIModalPresentationStyle
and UIModalTransitionStyle
.isModalInPresentation
and separately disabling the native swipe down gesture when the modal is using pageSheet
modalPresentationStyle
.ModalView
anywhere in your app and present a view modally either programmatically via a ref or automatically when a ModalView
is mounted/unmounted.UIBlurEffect
.pageSheet
modal behavior, and iOS also automatically handles the modal dismiss gesture when using a scrollview.# 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
ios/project.xcworkspace
projectPlease 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>
ModalView
Component PropsName | Default | Description |
---|---|---|
presentViaMount | false | If this prop is set to true, the modal will be presented or dismissed when the ModalView is mounted/unmounted. |
isModalBGBlurred | true | Set whether or not the background is blurred. When true, modalBGBlurEffectStyle prop takes effect. |
enableSwipeGesture | true | When the modal is using pageSheet or similar modalPresentationStyle , this prop controls whether or not the swipe gesture is enabled. |
hideNonVisibleModals | false | When multiple modals are visible at the same time, the first few modals will be temporarily hidden (they will still be mounted) to improve performance when this prop is set to true. |
isModalBGTransparent | true | Sets whether or not the modal background is transparent. When set to false, the background blur effect will be disabled automatically. |
isModalInPresentation | false | When set to true, it prevents the modal from being dismissed via a swipe gesture. The modal will still be swipeable, but the modal will not close when its swiped down but instead, it will bounce back up. |
setEnableSwipeGestureFromProps | false | When set to true, it allows you to set the enableSwipeGesture via the setEnableSwipeGesture function. |
setModalInPresentationFromProps | false | When set to true, it allows you to set theisModalInPresentation via the setIsModalInPresentation function. |
Name/Type | Default | Description |
---|---|---|
modalID: string |
Default: null |
Assign a unique ID to the modal. You can use the ID to refer to this modal when using the ModalViewModule functions and programatically control it. |
modalTransitionStyle: UIModalTransitionStyles value |
Default: coverVertical |
The transition style to use when presenting/dismissing a modal. If an invalid/unsupported value is passed, the default or the last supported value will be used. |
modalPresentationStyle: UIModalPresentationStyles value |
Default: automatic when on iOS 13+, otherwise overFullScreen |
The presentation style to use when presenting/dismissing a modal. If an invalid/unsupported value is passed, the default or the last supported value will be used. |
modalBGBlurEffectStyle: UIBlurEffectStyles value |
Default: systemThinMaterial when on iOS 13+, otherwise light |
The blur style to use for the UIBlurEffect modal background. If an invalid/unsupported value is passed, the default or the last supported value will be used. |
Name | Description |
---|---|
onModalFocus({nativeEvent}) |
Gets called when a modal is focused and is not currently the top most modal (to avoid duplicating the onModalShow event) |
onModalBlur({nativeEvent}) |
Gets called when a modal loses focus and is not currently the top most modal (to avoid duplicating the onModalDismiss event) |
onModalShow({nativeEvent}) |
Gets called after a modal is presented. |
onModalDismiss({nativeEvent}) |
Gets called after a modal is dismissed. |
onModalDidDismiss({nativeEvent}) |
Gets called after a modal is successfully dismissed via a swipe gesture. (Wrapper for UIAdaptivePresentationControllerDelegate.presentationControllerDidDismiss ). |
onModalWillDismiss({nativeEvent}) |
Gets called when a modal is being swiped down via a gesture. ((Wrapper for UIAdaptivePresentationControllerDelegate.presentationControllerWillDismiss ). |
onModalAttemptDismiss({nativeEvent}) |
Gets called when a modal is swiped down when isModalInPresentation is true. (Uses UIAdaptivePresentationControllerDelegate.presentationControllerDidAttemptToDismiss ). |
Name | Description |
---|---|
containerStyle | The style for the view that holds the modal contents. |
Name | Description |
---|---|
getEmitterRef() -> ModalVIewRef |
Gets a ref to the EventEmitter instance. |
aysnc setVisibility(visibility: bool, childProps: object) -> success: bool |
Programatically present/dismiss the modal. Resolved after the modal is presented/dismissed. |
aysnc getModalInfo() -> object: NativeEvent |
Get “native” info from the modal instance. Returns a NativeEvent object. |
aysnc setEnableSwipeGesture(bool) |
When setEnableSwipeGestureFromProps prop is true, it allows you to programatically set enableSwipeGesture prop via a function. |
async setIsModalInPresentation(bool) |
When setModalInPresentationFromProps prop is true, it allows you to programatically set isModalInPresentation via function. |
ModalViewModule
A NativeModule
that’s a collection of functions to programmatically control a ModalView
import { ModalViewModule } from 'react-native-ios-modal'
ModalViewModule.dismissAllModals(true)
Function | Description |
---|---|
async dismissModalByID(modalID: string) |
Close the ModalView with the corresponding modalID . Useful when you don’t have a direct ref to the ModalView component. |
async dismissAllModals(animated: bool) |
Closes all visible modals. |
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.
systemUltraThinMaterial
systemThinMaterial
systemMaterial
systemThickMaterial
systemChromeMaterial
systemMaterialLight
systemThinMaterialLight
systemUltraThinMaterialLight
systemThickMaterialLight
systemChromeMaterialLight
systemChromeMaterialDark
systemMaterialDark
systemThickMaterialDark
systemThinMaterialDark
systemUltraThinMaterialDark
regular
prominent
light
extraLight
dark
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
automatic
— Requires iOS 13 to work. The default presentation style for iOS 13 and above.fullScreen
— Present fullscreen but with an opaque background. The default presentation style on iOS 12 and below.overFullScreen
— Present fullscreen but with a transparent background.pageSheet
— The presentation style used on iPhones running iOS 13. Present a modal that can be dismissed via a swipe gesture.formSheet
— The presentation style used on iPads. Same as pageSheet
when on iPhone.none
currentContext
custom
overCurrentContext
popover
blurOverFullScreen
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
coverVertical
crossDissolve
flipHorizontal
partialCurl
ModalEventKeys
Enum values that you can use in the ModalView
EventEmitter
instance. Use the enum values to add/remove a listener.
import { ModalEventKeys } from 'react-native-ios-modal'
ModalView
EventEmitter
instance like this: modalEmitter.addListener(ModalEventKeys.onModalShow, this._handleOnModalShow)
modalEmitter.addListener('onModalShow', this._handleOnModalShow)
EventEmitter
like this: modalRef.getEmitterRef()
onModalBlur
onModalFocus
onModalShow
onModalDismiss
onModalDidDismiss
onModalWillDismiss
onModalAttemptDismiss
ModalContext
A context you can use inside the ModalView
component.
import { ModalContext } from 'react-native-ios-modal'
Object Key | Value Description |
---|---|
getModalRef | A function that returns a ref to the ModalView |
getEmitterRef | A function that returns a ref to the ModalView ’s EventEmitter instance |
setVisibility | A function that calls the ModalView setVisibility function |
setEnableSwipeGesture | A function that calls the ModalView setVisibility function |
setIsModalInPresentation | A function that calls the ModalView setIsModalInPresentation function |
withModalLifecycle
HOCA 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 { withModalLifecycle } from 'react-native-ios-modal'
export default withModalLifecycle(ModalContents);
onModalFocus({nativeEvent}){ ... }
ModalEventKeys
EventEmitter
Each ModalView
has an EventEmitter
instance, so the first step to use it is to get a ref to the emitter.
ModalView
, you can call modalRef.getEmitterRef()
to get a ref to the emitter instance.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
NativeEvent
objectExample {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 focusisPresented: bool
— whether or not the modal is visible or notmodalLevel: 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.AvailableBlurEffectStyles
ConstantAn 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.
import { AvailableBlurEffectStyles } from 'react-native-ios-modal';
AvailableBlurEffectStyles
will be empty.AvailablePresentationStyles
ConstantAn 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.
import { AvailablePresentationStyles } from 'react-native-ios-modal';
AvailablePresentationStyles
will be empty.Check out the examples directory for testing out the ModalView
.
Author: dominicstop
Source Code: https://github.com/dominicstop/react-native-ios-modal
#react-native #react #mobile-apps