[Bug]: CarPlay map view never sets GMSMapViewOptions.screen, so the navigation header and footer are sized for the phone

[spendres]

Is there an existing issue for this?

• I have searched the existing issues

Description of the bug

On a physical CarPlay head unit, a map view rooted in the CPWindow by BaseCarSceneDelegate renders its navigation UI at phone size. The guidance header's lane-guidance dropdown overlaps the ETA footer, and the type is far too large for the display. The map tiles and labels render correctly — only the navigation overlay is mis-sized.

GMSMapViewOptions has a screen property, added by the Navigation SDK's own category:

The screen the view will be used on.

Defaults to the main screen. Should be set to the CarPlay screen if this map view is to be used with CarPlay.

— GMSMapViewOptions+Navigation.h, GoogleNavigation 10.13.0

NavViewController.loadView never sets it:

GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];

if (_mapId && ![_mapId isEqualToString:@""]) {
  options.mapID = [GMSMapID mapIDWithIdentifier:_mapId];
}

if (_initialCameraPosition) {
  options.camera = _initialCameraPosition;
}

_mapView = [[GMSMapView alloc] initWithOptions:options];   // options.screen unset

grep -rn -i "uiscreen\|options.screen" ios example/ios/SampleApp at main returns nothing — not in the library, not in the CarPlay sample app. So every map view the library creates, including the one BaseCarSceneDelegate roots in the CPWindow, believes it is on UIScreen.mainScreen.

That the SDK does adapt to CarPlay is documented in GMSUISettings+Navigation.h: the trip progress bar "will not be shown for CarPlay displays" and "will only be shown when the GMSMapView is at least 552pt tall". It branches on the display and on height, and options.screen appears to be the public input for that — which the bridge never provides.

This is only visible if the app enables the navigation header/footer on the car screen. BaseCarSceneDelegate.onSessionAttached disables both by default and the sample does not override them, which is likely why it has gone unnoticed. Turning them on is the natural thing to do for an app that wants Google's turn-by-turn chrome on the console rather than building its own from didChangeNavInfo (per the guidance in #508).

Applications cannot work around this themselves: screen is an init-time option, there is no setter on GMSMapView, and NavViewController constructs the map view internally. It needs a fix in the library.

Suggested fix

Let the screen be supplied before the view loads, and have BaseCarSceneDelegate pass the car window's screen:

// NavViewController.h
- (void)setScreen:(nullable UIScreen *)screen;

// NavViewController.mm
- (void)setScreen:(nullable UIScreen *)screen {
  if (_mapView != nil) {
    RCTLogWarn(@"Cannot change screen after view is loaded");
    return;
  }
  _screen = screen;
}

// ... in loadView, before initWithOptions:
if (_screen != nil) {
  options.screen = _screen;
}

// BaseCarSceneDelegate.mm, in
// templateApplicationScene:didConnectInterfaceController:toWindow:
// — must precede the rootViewController assignment, which loads the view
self.navViewController = [[NavViewController alloc] init];
[self.navViewController setMapViewType:NAVIGATION];
[self.navViewController setScreen:window.screen];
self.navViewController.stateDelegate = self;

The phone NavigationView is unaffected — it never calls the setter and keeps the main-screen default.

I am running exactly this as a yarn patch. It compiles clean for x86_64 and arm64. I have not yet been able to confirm on a head unit whether it resolves the sizing, since I am waiting on a build — I will report back here either way. Happy to open a PR if the shape looks right to you.

React Native version

0.86.2

React version

19.2.3

Package version

0.16.3

Native SDK versions

• I haven't changed the version of the native SDKs

(GoogleNavigation 10.13.0 / GoogleMaps 10.13.0, pinned via a config plugin for react-native-maps coexistence.)

Steps to reproduce

1. Set up a CarPlay scene with BaseCarSceneDelegate as documented in CARPLAY.md.
2. Override onSessionAttached to enable the navigation header and footer:

   - (void)onSessionAttached {
     [self.navViewController setHeaderEnabled:YES];
     [self.navViewController setFooterEnabled:YES];
   }

3. Start a guidance session on the phone and connect to a CarPlay head unit.
4. The header and footer render at phone scale; on a short display the header's lane-guidance dropdown overlaps the ETA footer.

Note this needs real CarPlay hardware — the CarPlay simulator currently crashes on iOS runtimes above 26.3 (#607).

[spendres]

Reporting back as promised, with a negative result and an open question.

I shipped the patch described above (set options.screen in NavViewController.loadView, pass window.screen from BaseCarSceneDelegate before the rootViewController assignment) in a signed ad-hoc build and tested it on a physical head unit.

No change. The guidance header and ETA footer still render at phone proportions, with oversized type, and still overlap on the car display. The map itself continues to render correctly, so the split between "map fine / navigation UI mis-sized" is unchanged.

Two readings, and I can't distinguish them yet:

1. GMSMapViewOptions.screen doesn't govern the navigation UI's layout metrics, and the oversized chrome has some other cause.
2. My patch was a no-op, because window.screen isn't the CarPlay screen. CPWindow declares windowScene as NS_UNAVAILABLE, and in scene-based apps UIWindow.screen derives from windowScene.screen — so window.screen may simply return UIScreen.mainScreen, i.e. the value the option already defaults to. CarPlay predates scenes, so the legacy window.screen external-display mechanism might still apply and make it correct; I genuinely don't know.

If (2) is what's happening, the fix is the same shape but needs a different source for the screen, and BaseCarSceneDelegate is the only place that can know it.

Question for the maintainers: what is the intended way to obtain the CarPlay UIScreen for options.screen inside a CPTemplateApplicationSceneDelegate? CPTemplateApplicationScene exposes carWindow but no screen property, and CPWindow.windowScene is unavailable. If there's a supported accessor I've missed, I'll re-test with it and report back again.

Independent of that, the original observation stands: the library never sets options.screen anywhere, and Google's own header documents it as the property to set for a CarPlay map view. Even if it turns out not to be the cause of the sizing, that gap looks worth closing.

[spendres]

Correcting my previous comment, with measurements from the head unit.

I instrumented the scene delegate to report the screen identity on the CarPlay display itself. window.screen is the CarPlay screen — my doubt about CPWindow.windowScene being NS_UNAVAILABLE was unfounded, and the patch was not a no-op. Please disregard that question.

Measured on a real head unit (iPhone 17, iOS 26):

	bounds	scale	nativeScale
UIScreen.mainScreen	402 × 874	3.0	3.0
window.screen (== UIScreen.screens[1])	459 × 240	2.0	2.0

carWindow.bounds and navViewController.view.bounds are both 459 × 240, and the car window's userInterfaceIdiom is 3 (CarPlay). UIScreen.screens.count == 2, and window.screen != mainScreen.

So setting options.screen correctly does not fix the oversized navigation chrome. With the patch active and the correct CarPlay screen passed, the guidance header and ETA footer still render at phone proportions and still overlap on the car display.

The measurement suggests why, and it isn't about screen metrics at all: the display is 240pt tall. GMSUISettings+Navigation.h notes that the trip progress bar "will only be shown when the GMSMapView is at least 552pt tall", so the navigation UI is designed around considerably more vertical space than a CarPlay screen has. A guidance header with a lane-guidance dropdown plus an ETA footer doesn't fit in 240pt regardless of what screen the map view believes it is on.

That reframes this issue. Two separable things:

1. The options.screen gap is still real — the library never sets it, and the header documents it as the property to set for a CarPlay map view. window.screen inside templateApplicationScene:didConnectInterfaceController:toWindow: is a correct source, now measured. It just isn't the fix for chrome sizing. Worth closing on its own merits, or closing this issue if you'd rather not carry it.

2. The actual question: is enabling navigationHeaderEnabled / navigationFooterEnabled on a CarPlay map view supported at all? BaseCarSceneDelegate.onSessionAttached disables both, and the sample app doesn't override that — which now reads to me as deliberate rather than incidental. If that's right, it would help to say so in CARPLAY.md, because the override is an inviting one to write: without it the car screen shows a moving map with no maneuver banner and no ETA, which doesn't look like turn-by-turn.

For anyone arriving here with the same symptom: per @jokerttu's guidance on #508, the supported path is to render maneuver and ETA through CarPlay's own templates fed from GMSNavigationNavInfo via didChangeNavInfo, rather than enabling the SDK's phone chrome on the car screen. That's the direction I'm taking.

[spendres]

Closing the loop as promised. Outcome on our side: we stopped enabling the in-map header/footer on the CarPlay screen entirely and moved guidance to CarPlay's own templates (CPNavigationSession turn card + CPMapTemplate travel estimates), keeping the SDK's NavigationView as map-only on the car display. Road-verified across multiple drives: the platform chrome sizes correctly on the 459×240pt display, where the SDK's header/footer cannot (they need 552pt+ per GMSUISettings+Navigation.h's trip-progress-bar threshold — measurements earlier in this thread).

So for anyone else landing here: options.screen being unset by the library is real but is NOT the cause of oversized guidance chrome on CarPlay — the chrome simply doesn't fit a car display's height by design, and BaseCarSceneDelegate disabling it is correct. Platform templates are the workable path (as @jokerttu indicated in #508). We'd still suggest a docs note steering CarPlay users away from setHeaderEnabled/setFooterEnabled on the car view.