Mount one portal. Open a modal from any async flow and await a typed result on Expo, React Native, or the web.

Docs | GitHub | FAQ | Article

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<T>, 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.

const result = await magicModal.show<ConfirmationResult>(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.

Expo chooses versions compatible with the installed SDK.

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 for the portal and web command.

pnpm add magic-modal
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screens

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 covers pods, Android back handling, and iOS overlays.

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. A runnable App Router consumer lives in examples/next-web.

For bare React Native, follow the installation guide.

Expo and native applications mount one portal inside GestureHandlerRootView:

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { MagicModalPortal } from "magic-modal";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YourApp />
      <MagicModalPortal />
    </GestureHandlerRootView>
  );
}

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.

Use the same result type in show<T>() and useMagicModal<T>():

import { Pressable, Text, View } from "react-native";
import { MagicModalHideReason, magicModal, useMagicModal } from "magic-modal";

type ConfirmationResult = {
  confirmed: boolean;
};

function ConfirmationModal() {
  const { hide } = useMagicModal<ConfirmationResult>();

  return (
    <View>
      <Text accessibilityRole="header">Publish this release?</Text>
      <Pressable accessibilityRole="button" onPress={() => hide({ confirmed: true })}>
        <Text>Publish</Text>
      </Pressable>
      <Pressable accessibilityRole="button" onPress={() => hide({ confirmed: false })}>
        <Text>Cancel</Text>
      </Pressable>
    </View>
  );
}

export async function confirmRelease() {
  const result = await magicModal.show<ConfirmationResult>(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 <section> with <h2> and <button> and imports nothing from React Native. The result contract is identical either way.

Backdrop presses, completed swipes, system-dismiss actions, and hideAll() resolve the same promise with distinct reasons. System dismissal includes Android back, web Escape, and the native accessibility escape action. TypeScript exposes data after the caller narrows the result to INTENTIONAL_HIDE.

• Expo Web, iOS, and Android
• Next.js and web
• Modal flows and stacks
• Hide results
• Accessibility
• Advanced content replacement

The kitchen-sink Expo app contains runnable native flows. The interactive site runs the package in the browser.

Yes. Every show() call creates an independent stack entry with its own ID, configuration, and promise.

Yes. Disable swipe dismissal:

magicModal.show(ScrollableModal, {
  swipeDirection: undefined,
});

Magic Modal doesn't implement snap points or nested scrolling.

Keep the ID returned by show():

const { modalID } = magicModal.show(StatusModal);
magicModal.hide(undefined, { modalID });

Inside modal content, use useMagicModal().hide().

Temporarily call magicModal.disableFullWindowOverlay(). Restore it in a finally block after the picker closes. The native overlay guide contains the complete pattern.

See everyone who has contributed and read the contributing guide.

Magic Modal is licensed under the MIT License.