A React Native component to view a modal on iOS Device

A React Native component to view a modal on iOS Device

react-native-ios-modal

Intro:

React Native component to display modal on an iOS device 
by natively wrapping and presenting React Native view within UIViewController.
  • Since this is just using a UIViewController, this component also supports setting the UIModalPresentationStyle 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.

Info:

  • You can use this, but it’s only for iOS Devices (For Android You will have to use different Component Like: 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.

Installation:

You Can Install This component Via NPM OR YARN.

If You Are Installing Via NPM:

npm install react-native-ios-modal

OR

If You Are Installing Via YARN:

yarn add react-native-ios-modal

After Installing The Component You will need To update or install Pods in your iOS Directory(if You Are Using cocoapods).

cd ios && pod install

 


Installation Notes:

  • This library uses auto linking: 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

 


Demo Usage:

//First You need to import the library
import { ModalView } from 'react-native-ios-modal';

// then you can 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>

For More Demo You Can Checkout Example Directory.


Documentation:

D.1 – ModalView Component Props:

D.1.1 – Props: Flags:
NameDefaultDescription
presentViaMountfalseIf this prop is set to true, the modal will be presented or dismissed when the ModalView is mounted/unmounted. Note: Currently buggy/whip.
isModalBGBlurredtrueSet whether or not the background is blurred. When true, modalBGBlurEffectStyle prop takes effect.
enableSwipeGesturetrueWhen the modal is using pageSheet or similar modalPresentationStyle, this prop controls whether or not the swipe gesture is enabled.
hideNonVisibleModalsfalseWhen 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.
isModalBGTransparenttrueSets whether or not the modal background is transparent. When set to false, the background blur effect will be disabled automatically.
isModalInPresentationfalseWhen 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.
setEnableSwipeGestureFromPropsfalseWhen set to true, it allows you to set the enableSwipeGesture via the setEnableSwipeGesture function.
setModalInPresentationFromPropsfalseWhen set to true, it allows you to set theisModalInPresentation via the setIsModalInPresentationfunction.
D.1.2 – Props: Strings:
Name/TypeDefaultDescription
modalID: stringDefault: nullAssign 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 valueDefault: coverVerticalThe 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 valueDefault: automatic when on iOS 13+, otherwise overFullScreenThe 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 valueDefault: systemThinMaterial when on iOS 13+, otherwise lightThe 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.
D.1.3 – Props: Modal Events:
Name/TypeDescription
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).
D.1.4 – Props: Misc:
Name/TypeDescription
containerStyleThe style for the view that holds the modal contents.
D.1.5 – Props: Modal Functions:
NameDescription
getEmitterRef() -> ModalVIewRefGets a ref to the EventEmitter instance.
aysnc setVisibility(visibility: bool, childProps: object) -> success: boolProgramatically present/dismiss the modal. Resolved after the modal is presented/dismissed. Note: when a modal is hidden, the modal contents/children are unmounted and vice versa when modal is visible.
aysnc getModalInfo() -> object: NativeEventGet “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.

D.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)
FunctionDescription
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.

D.3 – Enum Values:

D.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.
  1. light
  2. extraLight
  3. dark
D.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
D.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
D.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

D.4 – ModalContext

A context you can use inside the ModalView component.

  • Import the context like this: import { ModalContext } from 'react-native-ios-modal'
Object KeyValue Description
getModalRefA function that returns a ref to the ModalView
getEmitterRefA function that returns a ref to the ModalView‘s EventEmitter instance
setVisibilityA function that calls the ModalView setVisibility function
setEnableSwipeGestureA function that calls the ModalView setVisibility function
setIsModalInPresentationA function that calls the ModalView setIsModalInPresentation function

D.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

D.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

D.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.

D.8 – Constants

D.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.
D.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.

https://github.com/dominicstop/react-native-ios-modal

If You Have Any Problem Or Doubts,
Please Do Ask Or Suggest In Comment.


Do Follow Us on:

Facebook.com

Twitter.com

Also CheckOut: SQLite3 Native Plugin for React Native

About: Aakash Kothari

I am passionate about my work. Because I love what I do, I have a steady source of motivation that drives me to do my best. In my last job, this passion led me to challenge myself daily and learn new skills that helped me to do better work


    Leave a Reply

    %d bloggers like this: