https://github.com/rodsarhan/react-native-magic-overlay
Show custom alerts on top of modals
https://github.com/rodsarhan/react-native-magic-overlay
android imperative ios modal react-native
Last synced: 4 months ago
JSON representation
Show custom alerts on top of modals
- Host: GitHub
- URL: https://github.com/rodsarhan/react-native-magic-overlay
- Owner: RodSarhan
- License: mit
- Created: 2023-01-23T10:31:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-01-23T18:35:55.000Z (over 2 years ago)
- Last Synced: 2025-06-21T20:03:33.767Z (4 months ago)
- Topics: android, imperative, ios, modal, react-native
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-native-magic-overlay
- Size: 352 KB
- Stars: 29
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
_An overlay library that can be called imperatively from anywhere and shows on top of other modals!_
## React Native Magic Overlay :sparkles:
This library enables displaying customizeable overlays that always appear on top of other modals, it can be called imperatively on Android and IOS device without having to worry about the other modals that currently exist in the component tree.
This library relies on the FullWindowOverlay component of [software-mansion/react-native-screens](https://github.com/software-mansion/react-native-screens) on IOS in order to render the view on top of other views, and on React Native's Modal component on Android.
## 📸 Examples
| IOS | Android |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 
| 
|
## 🛠 Installation
```sh
yarn add react-native-magic-overlay
```
## ⚙️ Usage
First, insert a `MagicOverlayPortal` at the top level of the application udner GestureHandlerRootView if it exists.
You can add a default style for the backdrop view in here if you don't want to use the default one or don't want to specify the backdrop style everytime the overlay is displayed.
```js
import {GestureHandlerRootView} from 'react-native-gesture-handler';
import {MagicOverlayPortal} from 'react-native-magic-overlay';
export default function App() {
return (
// <-- On the top of the app component hierarchy
// The rest of the app goes here
);
}
```
Then, you are free to use the `magicOverlay` as shown from anywhere you want.
```js
import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { magicOverlay } from 'react-native-magic-overlay';
const CustomAlert = (someProps) => (
Custom Alert
{
magicOverlay.hide({result: true})
}}> // This will hide the alert, resolve the promise with the passed object
OK
{
magicOverlay.hide({result: false})
}}> // This will hide the alert, resolve the promise with the passed object
Cancel
);
const showAlert = async () => {
// We can call it with or without props, depending on the requirements.
const result = await magicOverlay.show(CustomAlert);
//OR (with props)
const result = await magicOverlay.show();
console.log(result)
// will show {result: true}, or {result: false} based on the pressed button
};
export const Screen = () => {
return (
Show alert
);
};
```
Alternatively, if we don't care about waiting the resolved value of the promise we can just trigger some action instead.
```js
import React from 'react';
import {View, Text, TouchableOpacity} from 'react-native';
import {magicOverlay} from 'react-native-magic-overlay';
const CustomAlert = (props) => (
{
magicOverlay.hide();
props.onConfirm(true)
}}>
Confirm
);
export const Screen = () => {
const [confirmed, setConfirmed] = useState(false);
const showAlert = useCallback(
() => {
magicOverlay.show(
() => {setConfirmed(value)}}/>
)
}
,[])
return (
Show alert
);
};
```
magicOverlay.show( ) can take a second optional argument to pass extra props to the overlay such as backdropStyle
Example:
```js
magicOverlay.show(
() => ,
{backdropStyle: styles.overlayBackdrop}
)
```
## 😬 Notes
### State management
The overlay view is not reactive, as in the props that are passed to the component are a snapshot of when the overlay is displayed, so it's advised to use the overlay in the same way we use Alert.alert() and not rely on reactive values to control the texts or views inside it.
## 👨🏫 Contributing
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
## ⚖️ License
[MIT](LICENSE)