wix / wix/react-native-navigation
`showOverlay` creates a scene-less `UIWindow`, so overlays never appear under UIScene lifecycle
Nobody has claimed this yet.
- 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!
- Use UIScene lifecycle (
UIApplicationSceneManifest+UIWindowSceneDelegate). - Create the window with
initWithWindowScene:and pass it to RNN (delegate.windowset before bootstrap). - On
Navigation.events().registerAppLaunchedListener, do notsetRoot. Call:
Navigation.showOverlay({
component: {
name: 'example.OverlayScreen',
},
});
- OverlayScreen mounts (
componentDidMount/useEffectruns) but nothing is visible. The scene window is stillRNNSplashScreenViewController.
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+ customUIWindowSceneDelegate - Platform: iOS only
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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