Configure normal and low-light modes

Navigation SDK for iOS doesn't automatically follow iOS system light and dark modes. Instead, a navigation-enabled GMSMapView supports normal and low-light color schemes through its lightingMode property and the GMSNavigationLightingMode enum:

• Normal mode (.normal): Uses a color scheme suitable for daylight viewing.
• Low-light mode (.lowLight): Uses a color scheme suitable for night viewing.

Enable automatic lighting mode switching

Navigation SDK for iOS calculates the recommended lighting mode based on the time of day and the device's location, and exposes it through the suggestedLightingMode property of GMSNavigator. However, GMSMapView doesn't apply this recommendation automatically.

To switch between normal and low-light modes automatically, complete the following steps in your view controller:

1. Set the initial lighting mode at startup: When you set up the map, read the suggestedLightingMode property from GMSNavigator and assign that value to mapView.lightingMode. Because the listener only fires when the suggested lighting mode changes (such as at sunrise or sunset), setting the initial value ensures the map renders in low-light mode immediately if the user starts navigation at night.
2. Listen for lighting mode changes during navigation: Adopt the GMSNavigatorListener protocol and implement the navigator(_:didChangeSuggestedLightingMode:) method to update mapView.lightingMode whenever the suggested mode changes.

The following example shows how to set the initial lighting mode and update it when the suggested lighting mode changes:

// Step 1: Set the initial lighting mode on launch or setup.
mapView.navigator?.add(self)
mapView.lightingMode = mapView.navigator?.suggestedLightingMode ?? .normal

// Step 2: Update the lighting mode when the sun sets or rises during navigation.
func navigator(
  _ navigator: GMSNavigator,
  didChangeSuggestedLightingMode lightingMode: GMSNavigationLightingMode
) {
  mapView.lightingMode = lightingMode
}

// Step 1: Set the initial lighting mode on launch or setup.
[_mapView.navigator addListener:self];
_mapView.lightingMode = _mapView.navigator.suggestedLightingMode;

// Step 2: Update the lighting mode when the sun sets or rises during navigation.
- (void)navigator:(GMSNavigator *)navigator
    didChangeSuggestedLightingMode:(GMSNavigationLightingMode)lightingMode {
  _mapView.lightingMode = lightingMode;
}

For more information about adopting GMSNavigatorListener, see Declaring conformance to the required protocols in the Listen for navigation events guide.

Force normal or low-light mode

If you don't want the map to switch modes automatically, you can force normal or low-light mode by setting mapView.lightingMode directly and omitting the navigator(_:didChangeSuggestedLightingMode:) listener update.

The following example shows how to force the map into low-light or normal mode:

// Force low-light mode.
mapView.lightingMode = .lowLight

// Or force normal (daylight) mode.
mapView.lightingMode = .normal

// Force low-light mode.
_mapView.lightingMode = GMSNavigationLightingModeLowLight;

// Or force normal (daylight) mode.
_mapView.lightingMode = GMSNavigationLightingModeNormal;

Customize low-light UI colors

You can also customize the primary and secondary background colors of the navigation header when the map is in low-light mode. For more information about customizing these colors, see Low-light mode header colors in the Modify the navigation UI guide.