[iOS] Modal Bug: Invisible layer blocks UI when rapidly opening and closing modals

Description

There are two modals. When closing a first modal while opening a second modal, and then quickly closing the second modal, the second modal's native layer fails to dismiss properly on iOS, leaving an invisible layer that blocks user interaction with the UI.

This issue may be related to https://github.com/facebook/react-native/issues/48611

Steps to reproduce

1. When the first modal is closed while simultaneously opening a second modal
2. And the second modal is closed shortly after (within ~100ms)
3. The second modal's native layer remains on screen as an invisible layer
4. This invisible layer blocks all user interactions with the underlying UI
5. The app becomes unresponsive to touch events
6. The application is completely unusable and must be force-killed

React Native Version

0.77.1

Affected Platforms

Runtime - iOS

Output of npx @react-native-community/cli info

System:
  OS: macOS 15.3.1
  CPU: (12) x64 Intel(R) Core(TM) i7-8700B CPU @ 3.20GHz
  Memory: 52.50 MB / 16.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 18.20.6
    path: ~/.nvm/versions/node/v18.20.6/bin/node
  Yarn:
    version: 1.22.22
    path: /usr/local/bin/yarn
  npm:
    version: 10.8.2
    path: ~/.nvm/versions/node/v18.20.6/bin/npm
  Watchman:
    version: 2025.02.17.00
    path: /usr/local/bin/watchman
Managers:
  CocoaPods:
    version: 1.16.2
    path: /Users/leyserkids/.gem/ruby/2.7.7/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 24.2
      - iOS 18.2
      - macOS 15.2
      - tvOS 18.2
      - visionOS 2.2
      - watchOS 11.2
  Android SDK: Not Found
IDEs:
  Android Studio: 2024.1 AI-241.18034.62.2411.12169540
  Xcode:
    version: 16.2/16C5032a
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 11.0.26
    path: /usr/bin/javac
  Ruby:
    version: 2.7.7
    path: /Users/leyserkids/.rubies/ruby-2.7.7/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 15.0.1
    wanted: 15.0.1
  react:
    installed: 18.3.1
    wanted: 18.3.1
  react-native:
    installed: 0.77.1
    wanted: 0.77.1
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

Stacktrace or Logs

No errors logs

Reproducer

https://github.com/huanguolin/RnModalIosIssue

Screenshots and Videos

An invisible layer top on the UI:

When reproducing this issue, the following console output is observed:

Welcome to React Native DevTools
Debugger integration: iOS Bridgeless (RCTHost)
Running "RnModalIosIssue" with {"rootTag":1,"initialProps":{},"fabric":true}
---> handleShow 0
---> handleDismiss 1
---> handleDismiss 0

Workaround

A workaround for this issue is available in the workaround branch. When using the workaround, the console output shows proper modal opening and closing sequence:

Welcome to React Native DevTools
Debugger integration: iOS Bridgeless (RCTHost)
Running "RnModalIosIssue" with {"rootTag":1,"initialProps":{},"fabric":true}
---> handleShow 0
---> handleDismiss 0
---> handleShow 1
---> handleDismiss 1

workaround code:

import React, { forwardRef, useRef, useImperativeHandle, useState } from 'react';
import { Modal, ModalProps, Platform } from 'react-native';

// MyModal wraps the React Native Modal with the same API
// and implements a fix for iOS issues with multiple modals
const MyModal = forwardRef<any, ModalProps>((props, ref) => {
    const {
        visible,
        onShow,
        onDismiss,
        ...otherProps
    } = props;

    // Forward the ref to access the underlying Modal methods
    const modalRef = useRef<any>(null);
    useImperativeHandle(ref, () => ({
        ...(modalRef.current || {}),
    }));

    // Workaround for iOS modal issues
    const [innerVisible, setInnerVisible] = useState(visible);
    const [alreadyVisible, setAlreadyVisible] = useState(false);

    const handleDismiss = React.useCallback(() => {
        setAlreadyVisible(false);
        if (onDismiss) {
            onDismiss();
        }
    }, [onDismiss]);

    const handleShow = React.useCallback((e: any) => {
        setAlreadyVisible(true);
        if (onShow) {
            onShow(e);
        }
    }, [onShow]);

    React.useEffect(() => {
        // If Modal UI is not yet visible and needs to be shown, set internal state to visible
        if (!alreadyVisible && visible) {
            setInnerVisible(true);
        }
        // If Modal UI is already visible and needs to be hidden, set internal state to not visible
        if (alreadyVisible && !visible) {
            setInnerVisible(false);
        }
    }, [handleDismiss, alreadyVisible, visible]);

    return (
        <Modal
            ref={modalRef}
            visible={Platform.OS === 'ios' ? innerVisible : visible}
            onShow={handleShow}
            onDismiss={handleDismiss}
            {...otherProps}
        />
    );
});

export default MyModal;

从链接的 RnModalIosIssue 复现步骤和 React Native Modal 的 iOS 生命周期入手，将其快速关闭/打开序列与提供的 workaround 分支进行比较。跟踪原生 modal 层经过 show 和 dismiss 回调的过程；完成标准是快速切换两个 modal 时不再留下阻止 iOS 触摸交互的不可见层。