Introduction

React Native Magic Modal turns a modal interaction into a value you can await. Mount one portal near the app root. Call show() from anywhere.

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

TypeScript infers the return value from show() and hide().

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

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. Use Magic Modal for discrete interactions and async decisions.

Next step

Install the package and its peers. Mount the portal in your app root.