[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;

Bắt đầu với reproducer RnModalIosIssue được liên kết và vòng đời của React Native Modal trên iOS, đồng thời so sánh chuỗi đóng/mở nhanh của nó với branch workaround được cung cấp. Theo dõi lớp modal native qua các callback show và dismiss; hoàn thành khi việc chuyển nhanh giữa hai modal không còn để lại một lớp vô hình chặn tương tác cảm ứng trên iOS.