Installation
Install the packages required by your target runtime.
Choose the runtime the application ships. A browser-only application installs magic-modal and
nothing else: the web entry ships with zero React Native dependencies. Expo and bare React Native
load the native entry, which uses the full React Native stack, so those targets install the peer set
below. Expo Web counts as native here — it bundles through Metro under the react-native condition.
A project that ships several targets installs the union of those sets.
Expo Web
Run the shared React Native API in the browser.
Expo iOS
Install the native peers and run the iOS target.
Expo Android
Install the native peers and run the Android target.
Next.js
Add the portal to an App Router application. No bundler configuration.
The package is now called magic-modal
It used to be react-native-magic-modal. That name still resolves to the same
code: it is published as a thin package that depends on magic-modal and
re-exports it, released from the same commit at the same version. Existing
installs keep receiving updates and nothing needs to change today. New
projects should install magic-modal, and moving over is a dependency swap
plus a find-and-replace on the import specifier — the exported API is
identical.
Expo
Add Magic Modal with the project's package manager:
pnpm add magic-modalInstall only the peer set used by the target.
Expo Web
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-dom react-native-web @expo/metro-runtimeContinue with the Expo Web setup.
Expo iOS
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screensContinue with the Expo iOS setup.
Expo Android
npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screensContinue with the Expo Android setup. The iOS and Android commands match because both targets load the native package entry.
Expo's Babel preset configures Worklets. A default Expo project does not need another Babel plugin entry.
Next.js and other browser-only React apps
React and React DOM come with Next.js. Add Magic Modal:
pnpm add magic-modalThat is the whole install, and it is the same one for a plain React or Vite application: add
react and react-dom yourself if the framework does not already bring them. There is no bundler
configuration, no react-native-web, and no gesture or animation peer, because the browser entry
renders DOM elements and imports nothing but react.
The Next.js guide covers the Client Component root and the browser behavior.
Bare React Native
Install the package and native peers:
pnpm add magic-modal react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screensAdd the Worklets Babel plugin last:
module.exports = function (api) {
api.cache(true);
return {
presets: ["module:@react-native/babel-preset"],
plugins: [
// Existing plugins
"react-native-worklets/plugin",
],
};
};Install iOS pods:
npx pod-installReanimated 4 requires the New Architecture
Magic Modal 9 uses Reanimated 4. Migrate applications that still run React Native's legacy architecture before upgrading. Expo selects compatible Reanimated and Worklets versions for its SDK.
Upgrade from 8.0.0
Version 8.0.0 temporarily required Gesture Handler 3. Magic Modal 9 supports
Gesture Handler 2.20 and newer. Remove react-native-gesture-handler from
expo.install.exclude if the application added that workaround.
Continue to set up the portal.