Navigation Screen
The NAVIGATION screen is the main screen for the Android Auto navigation experience. It combines Free Drive, Route Preview, and Active Guidance in a single map screen and is available starting with Car API Level 7.
The screen observes the state of your app's MapboxNavigation instance and reacts to route changes automatically. You do not need to replace the screen when moving between previewing a route and navigating along it.
Choose the entry screen
On lower Car API levels, use the legacy FREE_DRIVE screen as the entry point to navigation:
val initialScreen = if (carContext.supportsUnifiedNavigation()) {
MapboxScreen.NAVIGATION
} else {
MapboxScreen.FREE_DRIVE
}
Keep the map setup, location permission checks, and navigation lifecycle management described in Get Started. Selecting NAVIGATION does not replace those setup steps.
React to navigation state
Internally, the screen's routes provider attaches to MapboxNavigation through MapboxNavigationApp. It reads the current active routes and route preview when attached, then listens for updates through RoutesObserver and RoutesPreviewObserver.
The screen chooses its mode from that state, in the following order:
| Navigation state | Screen mode | Camera mode |
|---|---|---|
| Active navigation routes are available | Active Guidance | Following |
| No active routes, but preview routes are available | Route Preview | Overview |
| Neither active nor preview routes are available | Free Drive | Following |
Active routes take precedence over preview routes. If a preview exists while MapboxNavigation has active routes, the screen continues showing Active Guidance. Clearing active routes returns to Route Preview if preview routes still exist, or Free Drive if they do not.
Changes made to the same MapboxNavigation instance elsewhere in your app, including on the phone, are reflected in the car screen. For example:
- Updating preview routes with
setRoutesPreview()shows Route Preview when there are no active routes. - Setting active routes with
setNavigationRoutes()switches to Active Guidance. - Clearing preview routes returns to Free Drive only when there are no active routes.
The screen updates its template when the mode or preview route list changes. Guidance information updates independently through CarNavigationInfoProvider, which requests a template refresh during Active Guidance when inline settings are closed.
Navigation modes
Free Drive
Free Drive uses a NavigationTemplate without turn-by-turn guidance. The camera follows the user's location, while map components display the location, road label, and speed limit.
Route Preview
Route Preview uses a MapWithContentTemplate containing a route list alongside the map. The camera switches to Overview so the driver can inspect the route.
The driver can select a route from the list or tap a route line on the map. Both interactions update the primary preview route. A map selection also refreshes the template so the list reflects the selected route. The number of routes shown in the list respects the car system's route-list content limit.
Selecting the navigation action starts guidance on the chosen preview route, retaining the other preview routes as alternatives. Pressing Back while previewing clears the preview instead of leaving the screen.
Active Guidance
Active Guidance uses a NavigationTemplate with turn-by-turn information and the car system's native travel-estimate card. The camera switches to Following. The route line, guidance markers, and navigation information update using the active navigation routes and guidance data.
When inline settings are open, pressing Back closes settings without clearing the route preview or stopping guidance. Otherwise, outside Route Preview, pressing Back delegates to MapboxScreenManager to navigate back.
Inline settings
The default action strips include a settings action in Free Drive, Route Preview, and Active Guidance. Selecting it shows a settings list alongside the map using a MapWithContentTemplate, without opening a separate screen or detaching the map renderers.
While settings are open, the settings panel replaces the route list or the maneuver and travel-estimate card. Android Auto controls the panel's position and size. Pressing Back restores the current navigation template. Settings also close when the navigation mode changes or another screen covers the navigation screen. Route-line taps do not change the preview selection while settings are open.
Without a custom provider, the inline panel uses the same stored settings as the legacy settings screen. To provide your own content, see Custom settings content.
Map components and lifecycle
The screen reuses the same map components across all three modes:
CarLocationRenderer: Displays the user's location.CarRoadLabelRenderer: Displays the road label.CarSpeedLimitRenderer: Displays speed-limit information.CarNavigationCamera: Handles Following and Overview camera modes and map gestures.CarRouteLineRenderer: Displays routes and handles route-line taps during preview.CarActiveGuidanceMarkers: Displays navigation markers.CarNavigationInfoProvider: Supplies guidance information for the template.
Switching modes does not detach and recreate these components. They stay registered while the screen is resumed, keeping the map in place as the navigation experience changes.
When the screen pauses, it unregisters the map components, clears the gesture handler, and unregisters its arrival trigger. It registers them again on resume and restores the camera mode appropriate to the current state. The routes provider remains registered for the screen's lifetime, from creation until destruction, so it can continue observing route state while another screen is on top.
Customize the screen
The screen reads route-line options, action-strip configuration, and the settings template provider from MapboxCarContext. Set these options when creating the context, before the screen is created, as shown in Get Started.
Route-line configuration
Set routeLineRendererOptions in the context's customize block. The screen passes these options to CarRouteLineRenderer when constructing it. A single renderer displays both preview routes and active navigation routes, so the configuration applies across Route Preview and Active Guidance.
import com.mapbox.maps.extension.androidauto.MapboxCarMap
import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
import com.mapbox.navigation.ui.androidauto.MapboxCarContext
import com.mapbox.navigation.ui.androidauto.preview.CarRouteLineRendererOptions
import com.mapbox.navigation.ui.androidauto.screenmanager.prepareScreens
// Inside your Session class. Keep the map setup described in Get Started.
@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
private val mapboxCarContext = MapboxCarContext(lifecycle, MapboxCarMap())
.prepareScreens()
.customize {
routeLineRendererOptions = CarRouteLineRendererOptions.Builder()
.build()
}
This example uses the default route-line options. Supply your configured CarRouteLineRendererOptions to customize rendering without replacing the navigation screen. Route-line configuration controls rendering, not route calculation or which routes are active: those still come from the observed MapboxNavigation state.
The renderer's route-click callback is connected to the screen's preview selection logic. Tapping a different preview route selects it and refreshes the route list; tapping a route outside Route Preview does not change the selection.
Mode-specific action strips
Set actionsStripProvider in the context's customize block to supply your action-strip provider. The screen reads the configured provider as options.actionStripProvider.
Although the screen is registered as MapboxScreen.NAVIGATION, it requests actions using the key for its current mode:
MapboxScreen.FREE_DRIVEMapboxScreen.ROUTE_PREVIEWMapboxScreen.ACTIVE_GUIDANCE
Use these keys to supply different actions for each mode, such as search during Free Drive or a stop-navigation action during Active Guidance. Handle the button callbacks in your provider; adding an action does not by itself change navigation state.
To keep inline settings in a custom action strip, use buildSettingsAction(screen) from com.mapbox.navigation.ui.androidauto.action. The helper opens inline settings on the unified navigation screen and the dedicated settings screen on legacy screens. It requires opting in to ExperimentalPreviewMapboxNavigationAPI.
The helper uses the default settings icon and no title. Pass a CarIcon with buildSettingsAction(screen, icon), a title with buildSettingsAction(screen, title = title), or both with buildSettingsAction(screen, icon, title). Titles count toward the car system's action-strip text limits.
The default unified Active Guidance strip already uses all four action slots: settings, feedback, audio guidance, and Stop. If you extend super.getActiveGuidance(screen), replace an existing action rather than appending a fifth one. The default strips omit the settings action while inline settings are open.
Custom settings content
Set settingsTemplateProvider in the context's customize block to a CarSettingsTemplateProvider. Its getSettingsTemplate(screen, mode) callback runs on each settings template request and receives the current CarSettingsMode: FREE_DRIVE, ROUTE_PREVIEW, or ACTIVE_GUIDANCE. These values are independent of the deprecated screen keys.
Return a ListTemplate with Action.BACK as its header action. The navigation screen handles closing settings and retains ownership of the map and navigation actions. When a setting changes, apply the change and call screen.invalidate() to refresh the settings content. Navigation-info updates do not refresh the settings panel.
The settings provider and mode APIs require opting in to ExperimentalPreviewMapboxNavigationAPI. This example supplies a voice-guidance mute toggle with a title for the current mode:
import androidx.car.app.model.Action
import androidx.car.app.model.Header
import androidx.car.app.model.ItemList
import androidx.car.app.model.ListTemplate
import androidx.car.app.model.Row
import androidx.car.app.model.Toggle
import com.mapbox.maps.extension.androidauto.MapboxCarMap
import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
import com.mapbox.navigation.ui.androidauto.MapboxCarContext
import com.mapbox.navigation.ui.androidauto.screenmanager.prepareScreens
import com.mapbox.navigation.ui.androidauto.settings.CarSettingsMode
import com.mapbox.navigation.ui.androidauto.settings.CarSettingsTemplateProvider
import com.mapbox.navigation.voice.api.MapboxAudioGuidance
// Inside your Session class. Keep the map setup described in Get Started.
@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
private val mapboxCarContext = MapboxCarContext(lifecycle, MapboxCarMap())
.prepareScreens()
.customize {
settingsTemplateProvider = CarSettingsTemplateProvider { screen, mode ->
val title = when (mode) {
CarSettingsMode.FREE_DRIVE -> "Free drive settings"
CarSettingsMode.ROUTE_PREVIEW -> "Route preview settings"
CarSettingsMode.ACTIVE_GUIDANCE -> "Active guidance settings"
}
val audioGuidance = MapboxAudioGuidance.getRegisteredInstance()
val muteRow = Row.Builder()
.setTitle("Mute voice guidance")
.setToggle(
Toggle.Builder { muted ->
if (muted) audioGuidance.mute() else audioGuidance.unmute()
screen.invalidate()
}
.setChecked(audioGuidance.stateFlow().value.isMuted)
.build()
)
.build()
ListTemplate.Builder()
.setHeader(
Header.Builder()
.setTitle(title)
.setStartHeaderAction(Action.BACK)
.build()
)
.setSingleList(ItemList.Builder().addItem(muteRow).build())
.build()
}
}
Use string resources for user-facing text in your app.
The provider customizes only inline settings, not legacy dedicated settings screens. A custom MapboxScreen.SETTINGS factory, such as the one in Get Started, does not affect the inline panel. MapboxScreen.SETTINGS and SettingsScreenFactory are deprecated; use inline settings on MapboxScreen.NAVIGATION on Car API Level 7 and higher. Dedicated settings screens are available for older car systems.