Magic Modal

While the MagicModalPortal component remains the same across platforms, your integration method depends on your runtime:

• Next.js and web: Add the portal to a Client Component. No special bundler configuration or React Native peer dependencies are required.
• Expo: Use the same root and modal components across iOS, Android, and web.
• iOS and Android: Requires specific handling for the Android back action and iOS native overlays.

Magic Modal provides a minimal API surface designed to manage a stack of modals. The core functionality is distributed across four main pillars:

1. MagicModalPortal: The single root component that must be mounted to own and render the modal stack.
2. magicModal: A global object used to show and hide stack entries from anywhere in your application code.
3. useMagicModal: A hook used to hide the current modal, specifically designed to return typed data back to the caller.
4. MagicModalHideReason: An enum representing the reasons why a modal was closed (e.g., via user interaction or programmatic dismissal).

When calling show<T>(), the returned promise resolves to a HideReturn<T> object. To safely distinguish between a user submitting data and a user cancelling the modal (e.g., by tapping the backdrop or pressing the back button), you must check the reason property before accessing the data property.

• Submission: If reason is MagicModalHideReason.INTENTIONAL_HIDE, the data property contains the submitted value of type T.
• Cancellation: If the reason is any other value, the modal was dismissed without submitting data, and the data property will not be present/available for use.

const result = await magicModal.show<FormValues>(FormModal, {
  accessibilityLabel: "Edit profile",
});

if (result.reason === MagicModalHideReason.INTENTIONAL_HIDE) {
  // Safely access result.data here
  await save(result.data);
}

Magic Modal manages the overlay positioning, but the content inside the modal is responsible for its own layout constraints. To ensure a good user experience, you must manually include standard React Native primitives within your modal component:

• SafeAreaView for notch/home indicator padding.
• KeyboardAvoidingView for handling keyboard overlap.
• ScrollView for content that exceeds device height.

Best Practice: For long forms, disable modal swipe dismissal (swipeDirection: undefined) to prevent gesture conflicts with the internal ScrollView.

When using Magic Modal in a Next.js or browser-only React environment, you do not need react-native, react-native-web, or any gesture/animation packages. The browser entry renders standard DOM elements and only requires react and react-dom.

Key integration requirements:

• The portal must be mounted within a Client Component.
• In the web environment, the portal can be mounted directly without a gesture root view.

Magic Modal separates the dialog surface from the orchestration logic. The component you use in your UI renders the dialog surface, while MagicModalPortal manages the backdrop, stack, animations, and the promise lifecycle.

To use Magic Modal, you must mount the MagicModalPortal exactly once at the root of your application (e.g., in your RootLayout).

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

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

When a modal is closed via a backdrop press or a swipe, the promise resolves with a reason but may not contain data. You must check the reason property against MagicModalHideReason.INTENTIONAL_HIDE to distinguish between a user-submitted action and a cancellation. This prevents attempting to access data that was never provided.

if (result.reason === MagicModalHideReason.INTENTIONAL_HIDE) {
  submit(result.data);
} else {
  trackCancellation(result.reason);
}

To use Magic Modal correctly, understand the following lifecycle and relationship between its core components:

1. MagicModalPortal: This component owns the modal stack. You should mount it once near your application root.
2. magicModal.show: This method pushes a new entry onto the stack and returns an awaitable handle (which is itself a Promise).
3. useMagicModal().hide: This hook provides the hide method used to close the current entry and pass typed data back to the caller.
4. Resolution: The promise returned by show() resolves to a HideReturn<T> object, which contains both the submitted data and the reason the modal was closed.

Note on Stacks: Every show() call creates an independent stack entry. Opening a second modal does not replace the first; it keeps the earlier entry and its associated promise in place.

When you await magicModal.show<T>(...), the returned object contains a reason and potentially data.

• Intentional Hides: If the component calls hide(data), the result reason is MagicModalHideReason.INTENTIONAL_HIDE. You should check this reason before accessing result.data to ensure type safety.
• System/External Dismissals: Dismissals via backdrop press, swipe, Android Back, web Escape, or hideAll() resolve the promise with their own specific reasons and no data is provided.
• Error Handling: Use try/catch blocks to handle any errors that occur during the asynchronous work following the modal result.