Adopt UINavigationBarAppearance.configureWithDefaultBackground so Stack headers can render the iOS 26 Liquid Glass material

[kajetangit]

What's missing

On iOS 26 with the Liquid Glass design enabled (no UIDesignRequiresCompatibility opt-out), there's no way to make the Stack header adopt the system Liquid Glass material. The bar is always either fully transparent (headerTransparent: true / alpha-0 background) or a flat opaque surface — never glass.

The per-button glass pill on UIBarButtonItem (back chevron, bar buttons) renders correctly, so UIKit is glass-aware in these builds. It's specifically the bar background that has no path through.

Why it's worth adding

Apple's HIG explicitly directs apps to let the navigation layer use the built-in Liquid Glass material:

"Avoid adding your own .background or another glassEffect to toolbars, as they already use the built-in Liquid Glass."

Today, any consumer of react-native-screens (including expo-router and @react-navigation/native-stack) is structurally unable to follow that guidance for the Stack header background.

Where it lives in the code

In ios/RNSScreenStackHeaderConfig.mm (verified on 4.23.0 and main), only two of the three UINavigationBarAppearance configure methods are ever called:

+ (UINavigationBarAppearance *)buildAppearance:(UIViewController *)vc
                                    withConfig:(RNSScreenStackHeaderConfig *)config
{
  UINavigationBarAppearance *appearance = [UINavigationBarAppearance new];

  if (config.backgroundColor && CGColorGetAlpha(config.backgroundColor.CGColor) == 0.) {
    [appearance configureWithTransparentBackground];
  } else {
    [appearance configureWithOpaqueBackground];   // catches nil and every opaque value
  }

  if (config.backgroundColor) {
    appearance.backgroundColor = config.backgroundColor;
  }
  // ...
}

configureWithDefaultBackground — the API that yields the system material (Liquid Glass on iOS 26, classic chrome on earlier versions) — isn't called anywhere in the iOS sources. That includes ios/gamma/stack/ (the experimental Stack v5 from 4.25.0-beta.*), where the navigation controller and screen controller are currently scaffold-only.

Suggested improvement

A third branch in buildAppearance: that calls [appearance configureWithDefaultBackground], opted into via whatever JS-side surface the maintainers prefer.

Related

• Adopt UISearchTab for role="search" on iOS 26+ to enable automatic search activation #4000 — "Adopt UISearchTab for role="search" on iOS 26+". Same shape of ask — surfacing an iOS 26 system default that react-native-screens hasn't adopted yet.
• Header title and buttons do not adapt to contrasting background (Liquid Glass) #3782 — adjacent issue about title/button tint colors not adapting under headerTransparent: true. Worth noting because headerTransparent is the nearest existing workaround, and Header title and buttons do not adapt to contrasting background (Liquid Glass) #3782 means it isn't a real path to the desired behavior.

Verified on

• react-native-screens: 4.23.0 (also main and 4.25.0-beta.*)
• iOS 26.x, Xcode 26.x
• React Native 0.81 (Expo SDK 55), New Architecture
• UIDesignRequiresCompatibility: not set (opted into Liquid Glass design)