iOS: system back button on the first screen of a nested stack (UINavigationItem.backAction, press handled in JS)

[enzomanuelmangano]

Note

Written by Claude Opus 5.5 on behalf of Enzo (@enzomanuelmangano).

The problem

The first screen of a nested native stack has no back button: UIKit only draws one when there is a previous item in the same UINavigationController. Apps that need one there (a nested stack opened from a tab or a parent stack, where "back" should leave the nested stack) end up drawing their own chevron as a custom headerLeft. On iOS 26 that custom button:

• doesn't match the system one (glass, size, chevron metrics, backButtonDisplayMode),
• doesn't take part in UIKit's bar-item transitions,
• loses the long-press back menu and the accessibility behaviour of the real back button.

Before / after

The first screen of a nested native stack. Top: today, a chevron drawn as headerLeft. Bottom: the system back button through backAction, with its press handled in JS (iOS 26.5 simulator).

Video, both pressed (left: drawn chevron, right: system button): https://github.com/enzomanuelmangano/repro-lab/blob/main/media/screens-system-back-button.mp4

Demo: https://github.com/enzomanuelmangano/repro-lab/tree/main/demos/screens-system-back-button. The v4 implementation used for it: enzomanuelmangano/repro-lab@main...feat/screens-system-back-button

What UIKit offers

Since iOS 16, UINavigationItem.backAction replaces the back button's action, and when the navigation item has nothing behind it, UIKit synthesizes the system back button for it. So a screen can show the real back button and still let JS decide what "back" means (pop the parent stack, close a modal, confirm discarding a draft):

navitem.backAction = [UIAction actionWithHandler:^(UIAction *action) {
  // forward the press to JS, e.g. an `onPressBackButton` event
}];

Idea

A header option (e.g. systemBackButton: true + an onPressBackButton event, or a backAction callback) that sets backAction on iOS 16+ and emits the press to JS instead of popping. Two details we found while implementing it:

• set the action once and look the header config up when it fires, so header updates don't hand UIKit a new back button each time (which restarts its transition);
• a synthesized button has no previous item to take backButtonDisplayMode from, so the item itself has to carry it.

We have this working on the v4 stack (RNSScreenStackHeaderConfig) in a production app. Given the focus on the new stack, would something like this fit v5's header API? If so, we're happy to open a PR against v5 in whatever shape you prefer.