Introduction

React Native Magic Modal turns a modal interaction into a value you can await. Mount one portal near the root of your app, then show a modal from a component, navigation handler, service, or plain function.

const result = await magicModal.show<ConfirmationResult>(() => (
  <ConfirmationModal />
)).promise;

if (
  result.reason === MagicModalHideReason.INTENTIONAL_HIDE &&
  result.data.confirmed
) {
  completePurchase();
}

Why use it?

Linear async flows

Write the interaction in the order a person experiences it—show, await, branch.

Typed results

The value returned by the modal is inferred through the show and hide calls.

Modal stacks

Show multiple modals, address them by ID, and update content without replacing the stack entry.

Gesture control

Choose a swipe direction, tune motion, or disable swipe for scrollable content.

The mental model

There are only three important pieces:

MagicModalPortal owns the modal stack. Mount it once.
magicModal.show pushes content from anywhere and returns a promise.
useMagicModal closes the current modal with typed data.

Designed for application modals

For a scroll-heavy bottom sheet with snap points, use a dedicated bottom-sheet library. Magic Modal is strongest when a modal represents a discrete interaction or async decision.

Next step

Install the package and its peers, then mount the portal in your app root.