> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/llms.txt)

# 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.

![A Android Auto screenshot of the free drive screen.](https://docs.mapbox.com/android/assets/ideal-img/navigation-androidauto-nav-template.f3ee29e.480.png)

## Choose the entry screen

On lower Car API levels, use the [`FREE_DRIVE`](https://docs.mapbox.com/android/navigation/guides/androidauto/free-drive) screen as the entry point to navigation:

```kotlin
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](https://docs.mapbox.com/android/navigation/guides/androidauto/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 when its information changes.

## 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

![A Android Auto screenshot of the free drive screen.](https://docs.mapbox.com/android/assets/ideal-img/navigation-androidauto-nav-preview.b4329b8.480.png)

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.

Outside Route Preview, pressing Back delegates to `MapboxScreenManager` to navigate back.

## 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 and action-strip configuration from `MapboxCarContext`. Set these options when creating the context, before the screen is created, as shown in [Get Started](https://docs.mapbox.com/android/navigation/guides/androidauto/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.

```kotlin
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_DRIVE`
-   `MapboxScreen.ROUTE_PREVIEW`
-   `MapboxScreen.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.