Installation

Install the package

pnpm add react-native-magic-modal react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screens

Expo

Let Expo select native versions compatible with your SDK:

npx expo install react-native-gesture-handler react-native-reanimated react-native-worklets react-native-screens
pnpm add react-native-magic-modal

No gesture-handler exclusion is needed. Magic Modal 9 supports both the 2.x builder API and the 3.x hook API.

Next.js

Install React Native Web:

pnpm add react-native-web

Next 16 uses Turbopack by default. Point React Native imports at React Native Web and resolve platform files first:

next.config.ts

import type { NextConfig } from "next";

const config = {
  transpilePackages: [
    "react-native-magic-modal",
    "react-native-gesture-handler",
    "react-native-reanimated",
    "react-native-screens",
    "react-native-web",
    "react-native-worklets",
  ],
  turbopack: {
    resolveAlias: {
      "react-native": "react-native-web",
    },
    resolveExtensions: [
      ".web.tsx",
      ".web.ts",
      ".web.jsx",
      ".web.js",
      ".web.mjs",
      ".web.cjs",
      ".tsx",
      ".ts",
      ".jsx",
      ".js",
      ".mjs",
      ".cjs",
      ".json",
    ],
  },
} satisfies NextConfig;

export default config;

The interactive demo on this site uses this setup.

Minimum versions

Package	Version
React	18.0.0
React Native	0.81.0
React Native Gesture Handler	2.20.0
React Native Reanimated	4.1.0
React Native Worklets	0.5.0
React Native Screens	4.19.0

Reanimated 4 requires the New Architecture

Reanimated 4 only supports React Native's New Architecture. If your app still runs on the legacy architecture, migrate it before installing Magic Modal 9. Keep Worklets on a version supported by your Reanimated minor; Expo chooses that pair for you.

Bare React Native

Add the Worklets Babel plugin last in your plugin list:

babel.config.js

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-install

Expo's default Babel setup already includes the required plugin. react-native-screens powers the iOS full-window overlay used by the portal; install it even if your navigator already brings it transitively.

Upgrade from 8.0.0

Version 8.0.0 temporarily required Gesture Handler 3. Upgrade Magic Modal to 9 or newer, and remove react-native-gesture-handler from expo.install.exclude if you added it.

Continue to set up the portal.