wix / wix/react-native-navigation

`showOverlay` creates a scene-less `UIWindow`, so overlays never appear under UIScene lifecycle

Open
#8,345 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

platform: iOS type: accepted/bug
Dominant language
MDX
Stars
13.2k
Forks
2.6k
Avg merge
6d 2h
Merged PRs (30d)
1

Description

What happened?

On iOS, Navigation.showOverlay() creates a new RNNOverlayWindow with initWithFrame: and never assigns a UIWindowScene.

With a scene-based app lifecycle, that window is not added to the scene, so the overlay never appears. JS still mounts and runs (the overlay VC is created and rendered), which makes this look like a hang: native/RNN splash dismisses, overlay logic is running, but the screen stays on RNNSplashScreenViewController / the current root.

Navigation.setRoot() is not affected, because it attaches the layout to the existing _mainWindow that the host already bound to the scene.

This is easy to miss on older iOS if the app still used the AppDelegate window path. It becomes a hard break once the app adopts UIWindowScene (mandatory on iOS 26+).

What was the expected behaviour?

showOverlay shows the overlay above the current root on the same UIWindowScene.

Was it tested on latest react-native-navigation?
  • I have tested this issue on the latest react-native-navigation release and it still reproduces.
Help us reproduce this issue!
  1. Use UIScene lifecycle (UIApplicationSceneManifest + UIWindowSceneDelegate).
  2. Create the window with initWithWindowScene: and pass it to RNN (delegate.window set before bootstrap).
  3. On Navigation.events().registerAppLaunchedListener, do not setRoot. Call:
Navigation.showOverlay({
  component: {
    name: 'example.OverlayScreen',
  },
});
  1. OverlayScreen mounts (componentDidMount / useEffect runs) but nothing is visible. The scene window is still RNNSplashScreenViewController.

Control: the same screen shown via setRoot appears correctly:

Navigation.setRoot({
  root: {
    stack: {
      children: [{ component: { name: 'example.OverlayScreen' } }],
    },
  },
});
In what environment did this happen?
  • react-native-navigation: 8.8.9
  • react-native: 0.87 (New Architecture / Fabric, bridgeless)
  • iOS: 26 / 27 (also repros conceptually on iOS 13+ with UIScene)
  • Host: RNNAppDelegate + custom UIWindowSceneDelegate
  • Platform: iOS only

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the native implementation of Navigation.showOverlay and RNNOverlayWindow, especially the initWithFrame: path, and compare it with the existing _mainWindow handling used by setRoot. Reproduce with a UIWindowSceneDelegate and verify that the overlay window is associated with the host UIWindowScene. Done means showOverlay appears above the current root while the existing setRoot behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
ios, react-native
Domain
mobile
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.