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

Installation

Expo chooses versions compatible with the installed SDK.

Expo Web

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.

Expo iOS

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

Expo Android

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.

Next.js and other browser-only React apps

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.

Mount the portal

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.

Return typed data

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.

Documentation

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

FAQ

Can multiple modals be open?

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

Can a modal contain a ScrollView?

Yes. Disable swipe dismissal:

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

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

How do I close a modal from outside its component?

Keep the ID returned by show():

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

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

How do I render below a native picker on iOS?

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

Contributors

See everyone who has contributed and read the contributing guide.

License

Magic Modal is licensed under the MIT License.