docs/internals/mobile-navigation.md

Mobile navigation headers

The iOS Home and thread routes share the root native stack in Stack.tsx. Keeping them in one navigation controller lets UIKit animate the header between routes. The iPad sidebar owns a separate, single-screen stack; Android uses its own in-flow headers.

On Liquid Glass iOS, Home keeps a transparent native title and renders its brand as a custom leading item. A custom headerTitle previously shortened the scroll fade and removed the blur behind the logo. Preserve the native title when changing the brand or its connection-status replacement.

Both brand states use BRAND_HEADER_ITEM_IDENTIFIER from CompactBrandTitle.tsx. The native-stack and react-native-screens patches forward custom item identifiers to UIBarButtonItem.identifier, just as they do for native buttons and menus. UIKit otherwise matches transition items using their position and content, so the brand needs an explicit identity separate from navigation controls. Connection status changes retain that identity. See Apple's identifier documentation.

The react-native-screens patch caches leading, trailing, and center item groups independently. A button can belong to only one group: constructing another group with the same button removes it from the previous one. Unrelated menu updates must therefore preserve the other groups while UIKit may be animating them. Each cache includes the owning header config, its item values, and custom native item identities, so changed content or remounted event emitters still rebuild.

Custom header identifiers require native code generation and a new mobile build; an over-the-air JavaScript update alone is insufficient. The Android view manager implements the generated identifier setter as a no-op because this behavior is specific to iOS 26 and later.