## How it works
1. `MagicModalPortal` owns the modal stack. Mount it once, near the root.
2. `magicModal.show()` pushes one entry and returns an awaitable handle.
3. `useMagicModal().hide(data)` closes that entry with typed data.
4. The handle resolves to `HideReturn`, including the close reason.
The handle is the promise itself, carrying that entry's `modalID`, `update`, and `hide`. The caller
resumes with submitted data or the exact dismissal reason.
```tsx
const result = await magicModal.show(ConfirmationModal, {
accessibilityLabel: "Confirm publish",
});
if (result.reason === MagicModalHideReason.INTENTIONAL_HIDE) {
await publish(result.data);
} else {
recordCancellation(result.reason);
}
```
`const { promise, modalID, update } = magicModal.show(...)` still works; `promise` is a deprecated
alias of the handle itself.
Every stack entry keeps its own component, configuration, ID, and promise. A second `show()` call
can open above the current modal without mixing their results.
## Installation
Expo chooses versions compatible with the installed SDK.
### Expo Web
```bash
pnpm add magic-modal
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-dom react-native-web @expo/metro-runtime
```
Expo Web bundles through Metro under the `react-native` condition, so it loads the native entry and
takes the same peers as iOS and Android. The browser-only install is the Next.js one below. Read the
[Expo guide](https://magic-modal.gabrieltaveira.dev/docs/platforms/expo/) for the portal and web
command.
### Expo iOS
```bash
pnpm add magic-modal
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screens
```
### Expo Android
```bash
pnpm add magic-modal
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screens
```
iOS and Android use the same native dependency set. The
[native guide](https://magic-modal.gabrieltaveira.dev/docs/platforms/ios-android/) covers
pods, Android back handling, and iOS overlays.
### Next.js and other browser-only React apps
```bash
pnpm add magic-modal
```
That is the whole install. The web entry ships with zero React Native dependencies, so a browser
application needs no bundler alias and no gesture or animation peer. The native entries use the full
React Native stack, which is why the Expo commands above install more. Copy the Client Component
setup from the [Next.js guide](https://magic-modal.gabrieltaveira.dev/docs/platforms/nextjs/). A
runnable App Router consumer lives in [`examples/next-web`](examples/next-web).
For bare React Native, follow the
[installation guide](https://magic-modal.gabrieltaveira.dev/docs/getting-started/installation/).
## Mount the portal
Expo and native applications mount one portal inside `GestureHandlerRootView`:
```tsx
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { MagicModalPortal } from "magic-modal";
export default function App() {
return (
);
}
```
With Expo Router, put the same structure in the root `app/_layout.tsx`.
A browser application mounts `MagicModalPortal` inside a Client Component and nothing else. There is
no `GestureHandlerRootView`, because there is no Gesture Handler in the browser bundle. Copy the
shell from the [web setup](https://magic-modal.gabrieltaveira.dev/docs/platforms/nextjs/).
## Return typed data
Use the same result type in `show()` and `useMagicModal()`:
```tsx
import { Pressable, Text, View } from "react-native";
import { MagicModalHideReason, magicModal, useMagicModal } from "magic-modal";
type ConfirmationResult = {
confirmed: boolean;
};
function ConfirmationModal() {
const { hide } = useMagicModal();
return (
Publish this release? hide({ confirmed: true })}>
Publish hide({ confirmed: false })}>
Cancel
);
}
export async function confirmRelease() {
const result = await magicModal.show(ConfirmationModal, {
accessibilityLabel: "Publish this release",
});
if (result.reason !== MagicModalHideReason.INTENTIONAL_HIDE) {
return { confirmed: false, reason: result.reason };
}
return result.data;
}
```
That modal is the React Native one. The browser entry renders DOM, so the same modal on the web is a
`` with `
