Map and app design

SDKs covered:
Navigation SDK
Navigation UI SDK

Use the Navigation UI SDK to design an application that provides a unique experience for your users or fits your brand. The Navigation UI SDK offers a wide range of options for customizing the look of your application including navigation instructions, route lines, and the map style.

Day and Night mode

If you're using NavigationLauncher or NavigationView within your own Activity or Fragment the view will update based on whatever the current mode is in the Activity. The current night mode is determined by AppCompatDelegate#getDefaultNightMode().

Style the map route

You can use NavigationMapRoute to draw the route line on your map. Instantiate it with a MapView, MapboxMap and LifecycleOwner, then add a DirectionsRoute from our Directions API. The DirectionsRoute will automatically be added (even in off-route scenarios) if you instantiate with MapboxNavigation. You can also style the route with a given style:

NavigationMapRoute mapRoute = new NavigationMapRoute.Builder(mapView, map, lifecycleOwner).build();

The given style will determine route color, congestion colors, and the route scale:

    <style name="NavigationMapRoute">
        <!-- Colors -->
        <item name="routeColor">@color/mapbox_navigation_route_layer_blue</item>
        <item name="routeLowCongestionColor">@color/mapbox_navigation_route_layer_blue</item>
        <item name="routeUnknownCongestionColor">
        <item name="routeModerateCongestionColor">
        <item name="routeHeavyCongestionColor">
        <item name="routeSevereCongestionColor">
        <item name="routeShieldColor">@color/mapbox_navigation_route_shield_layer_color</item>
        <item name="routeLineTraveledColor">@color/mapbox_navigation_route_line_traveled_color
        <item name="`routeLineShieldTraveledColor`">@color/mapbox_navigation_route_shield_line_traveled_color
        <item name="alternativeRouteColor">@color/mapbox_navigation_route_alternative_color</item>
        <item name="alternativeRouteUnknownCongestionColor">
        <item name="alternativeRouteLowCongestionColor">
        <item name="alternativeRouteModerateCongestionColor">
        <item name="alternativeRouteHeavyCongestionColor">
        <item name="alternativeRouteSevereCongestionColor">
        <item name="alternativeRouteShieldColor">
        <!-- Scales -->
        <item name="routeScale">1.0</item>
        <item name="routeTrafficScale">1.0</item>
        <item name="alternativeRouteScale">1.0</item>
        <item name="upcomingManeuverArrowColor">
        <item name="upcomingManeuverArrowBorderColor">

        <!-- Expression styling -->
        <item name="roundedLineCap">true</item>

Customize route color behind the puck

The routeLineShieldTraveledColor and routeLineTraveledColor style items represent the section of the route line that your user has traveled. When this feature is enabled the section of the route line behind the puck will be updated during navigation to match the styling you have defined. For example, to make the traveled part of the route line appear gray and only partially visible use a value like #55a8aaba. To make the line invisible use #00000000. Remember that the route line is on a layer above the shield line so to achieve full or partial transparency both style items should be adjusted. This feature is disabled by default. The NavigationMapRoute, NavigationMapboxMap and NavigationViewOptions classes have options to enable this feature.

Style the NavigationView

You can also style the NavigationView colors. This includes the style of the map and/or route. To do this, provide a light and dark style in the XML where you have put your NavigationView:


Each style must provide a value for every custom attribute or have a parent style (NavigationViewLight or NavigationViewDark) or the View will not properly inflate. Our default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

An example of how to create your own style can be found by looking at one of our default styles like

<style name="MyCustomTheme" parent="NavigationViewLight">
   <item name="navigationViewPrimary">@color/mapbox_navigation_route_alternative_congestion_red</item>
   <item name="navigationViewSecondary">@color/mapbox_navigation_route_layer_blue</item>
    <!-- Map style URL -->
    <item name="navigationViewMapStyle">@string/navigation_guidance_day_v3</item>

Here are a two more examples of custom themes. CustomNavigationMapRoute is for the route line shown and is used in CustomNavigationViewLight which allows you to customize the remaining NavigationView colors, as well as the map style. Both have comments outlining where the given color should show on the screen:

    <style name="CustomNavigationMapRoute" parent="@style/NavigationMapRoute">
        <!-- Main color for the route line -->
        <item name="routeColor">#4882C6</item>
        <!-- Outline color for the route line -->
        <item name="routeShieldColor">#2C5F99</item>
        <!-- Color for moderate traffic along the route line -->
        <item name="routeModerateCongestionColor">#FFAB65</item>
        <!-- Color for severe traffic along the route line -->
        <item name="routeSevereCongestionColor">#E85552</item>
        <item name="routeLineTraveledColor">#55a8aaba</item>
        <!-- Scales -->
        <item name="routeScale">1.0</item>
    <style name="CustomNavigationViewLight" parent="@style/NavigationViewLight">
        <!-- The main turn banner view at the top of the screen -->
        <!-- Background color of the banner -->
        <item name="navigationViewBannerBackground">#FFFFFF</item>
        <!-- Color for the primary label that displays the turn name -->
        <item name="navigationViewBannerPrimaryText">#37516F</item>
        <!-- Color for the secondary label that occasionally appears underneath the primary label -->
        <item name="navigationViewBannerSecondaryText">#E637516F</item>
        <!-- Primary color for the turn arrow icons-->
        <item name="navigationViewBannerManeuverPrimary">#37516F</item>
        <!-- Secondary color for the turn arrow icons (e.g. the line segment that forks off) -->
        <item name="navigationViewBannerManeuverSecondary">#4D37516F</item>
        <!-- Alternate background color for the dropdown list of upcoming steps -->
        <item name="navigationViewListBackground">#FAFAFA</item>

        <!-- The summary view along the bottom of the screen -->
        <!-- Background color of the summary view -->
        <item name="navigationViewPrimary">#FFFFFF</item>
        <!-- Tint color for icons in the summary view -->
        <item name="navigationViewSecondary">#28353D</item>
        <!-- Accent color for elements such as the recenter button -->
        <item name="navigationViewAccent">#4882C6</item>
        <!-- Color for the main duration label in the summary view -->
        <item name="navigationViewPrimaryText">#424242</item>
        <!-- Color for the secondary distance and ETA label in the summary view -->
        <item name="navigationViewSecondaryText">#424242</item>

        <!-- Custom colors for progress bars displayed during navigation -->
        <item name="navigationViewProgress">#4B75A4</item>
        <item name="navigationViewProgressBackground">#39587B</item>

        <!-- Custom colors for the route line and traffic -->
        <item name="navigationViewRouteStyle">@style/CustomNavigationMapRoute</item>

        <!-- Map style -->
        <item name="navigationViewMapStyle">mapbox://styles/mapbox/navigation-guidance-day-v2</item>

Please reference the diagram below to see where these attribute names align within the actual UI:

LetterResource name
HnavigationViewLocationLayerStyle> mapbox_gpsDrawable
InavigationViewRouteStyle > upcomingManeuverArrowBorderColor
JnavigationViewRouteStyle > upcomingManeuverArrowColor
KnavigationViewRouteStyle > routeColor
LnavigationViewRouteStyle > routeSevereCongestionColor
MnavigationViewRouteStyle > routeShieldColor
Was this page helpful?