Installation
Install the packages required by your target runtime.
Choose the runtime the application ships. Expo Web uses browser packages. Expo iOS and Android use the same native dependency set. 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
Configure React Native Web in an App Router application.
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
React and React DOM come with Next.js. Add Magic Modal and its browser runtime:
pnpm add magic-modal react-native react-native-web react-native-gesture-handler react-native-reanimated react-native-workletsThe Next.js guide contains the validated Turbopack alias, extension order, transpilation list, and Client Component root.
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.