Skip to main content

Map and app design

A newer version of the Navigation SDK is available
This page uses v1.6.2 of the Mapbox Navigation SDK. A newer version of the SDK is available. Learn about the latest version, v2.20.2, in the Navigation SDK documentation.
mobile Navigation UI SDK

All content on this page refers to the 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 map style.

Day and night mode

If you're using 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().

Maneuver instructions

You can apply custom colors to the Maneuver instructions displayed in the InstructionView. To do this, provide a custom instruction view style in the XML where you have put your InstructionView:

<com.mapbox.navigation.ui.instruction.InstructionView
android:id="@+id/instructionView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
style="@style/CustomInstructionView" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (InstructionView). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the InstructionView:

<style name="CustomInstructionView">
{/* Color of the banner view background */}
<item name="instructionViewPrimaryBackgroundColor">@color/navigation_instruction_view_primary_background</item>
{/* Color of the banner reroute view background */}
<item name="instructionViewSecondaryBackgroundColor">@color/navigation_instruction_view_secondary_background</item>
{/* Alternate background color for the dropdown list of upcoming steps */}
<item name="instructionListViewBackgroundColor">@color/navigation_instruction_list_view_background</item>
{/* Color of the banner view primary label that displays the turn name */}
<item name="instructionViewPrimaryTextColor">@color/navigation_instruction_view_primary_text</item>
{/* Color for the secondary label that occasionally appears underneath the primary label */}
<item name="instructionViewSecondaryTextColor">@color/navigation_instruction_view_secondary_text</item>
{/* Style for the maneuver view */}
<item name="instructionViewManeuverViewStyle">@style/CustomManeuverView</item>
{/* Style for the sound button */}
<item name="instructionViewSoundButtonStyle">@style/CustomSoundButton</item>
{/* Style for the feedback button */}
<item name="instructionViewFeedbackButtonStyle">@style/CustomFeedbackButton</item>
{/* Style for the alert view */}
<item name="instructionViewAlertViewStyle">@style/CustomAlertView</item>
</style>

Feedback button

You can apply custom colors to the FeedbackButton. To do this, provide a custom feedback button style in the XML where you have put your FeedbackButton:

<com.mapbox.navigation.ui.FeedbackButton
android:id="@+id/feedbackButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/CustomFeedbackButton" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (FeedbackButton). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the FeedbackButton:

<style name="CustomFeedbackButton">
{/* Feedback button background color */}
<item name="feedbackButtonPrimaryColor">@color/navigation_primary_background</item>
{/* Feedback icon tint color */}
<item name="feedbackButtonSecondaryColor">@color/navigation_secondary_background</item>
</style>

Recenter button

You can apply custom colors to RecenterButton. To do this, provide a custom recenter button style in the XML where you have put your RecenterButton:

<com.mapbox.navigation.ui.RecenterButton
android:id="@+id/recenterButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/CustomRecenterButton" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (RecenterButton). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the RecenterButton:

<style name="CustomRecenterButton">
{/* Recenter button background color */}
<item name="recenterButtonPrimaryColor">@color/navigation_primary_background</item>
{/* Recenter button text color */}
<item name="recenterButtonSecondaryColor">@color/navigation_accent</item>
</style>

Alert view

You can apply custom colors to AlertView. To do this, provide a custom alert view style in the XML where you have put your AlertView:

<com.mapbox.navigation.ui.alert.AlertView
android:id="@+id/alertView"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/CustomAlertView" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (AlertView). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the AlertView:

<style name="CustomAlertView">
{/* Alert view background color */}
<item name="alertViewBackgroundColor">@color/navigation_primary_background</item>
{/* Alert view progress bar background color */}
<item name="alertViewProgressBarBackgroundColor">@color/navigation_progress_bar_background</item>
{/* Alert view progress bar color */}
<item name="alertViewProgressBarColor">@color/navigation_progress_bar</item>
{/* Alert view message text color */}
<item name="alertViewTextColor">@color/navigation_instruction_view_primary_text</item>
</style>

Way name view

You can apply custom colors to the WayNameView. To do this, provide a custom way name view style in the XML where you have put your WayNameView:

<com.mapbox.navigation.ui.map.WayNameView
android:id="@+id/wayNameView"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/CustomWayNameView" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (WayNameView). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the WayNameView:

<style name="CustomWayNameView">
{/* Way name view background color */}
<item name="wayNameViewPrimaryColor">@color/navigation_primary_background</item>
{/* Way name view text color */}
<item name="wayNameViewSecondaryColor">@color/navigation_secondary_background</item>
</style>

Summary bottom sheet

You can apply custom colors to the SummaryBottomSheet. To do this, provide a summary bottom sheet style in the XML where you have put your SummaryBottomSheet

<com.mapbox.navigation.ui.summary.SummaryBottomSheet
android:id="@+id/summaryBottomSheet"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/CustomSummaryBottomSheet" />
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (SummaryBottomSheet). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the SummaryBottomSheet:

<style name="CustomSummaryBottomSheet">
{/* Summary bottom sheet background color */}
<item name="summaryBottomSheetPrimaryColor">@color/navigation_primary_background</item>
{/* Summary bottom sheet icon tint color */}
<item name="summaryBottomSheetSecondaryColor">@color/navigation_secondary_background</item>
{/* Summary bottom sheet divider view color */}
<item name="summaryBottomSheetDividerColor">@color/navigation_divider</item>
{/* Summary bottom sheet reroute progress bar background color */}
<item name="summaryBottomSheetProgressBarColor">@color/navigation_accent</item>
{/* Summary bottom sheet primary text color (e.g. the remaining time label) */}
<item name="summaryBottomSheetPrimaryTextColor">@color/navigation_primary_text</item>
{/* Summary bottom sheet secondary text color (e.g. the remaining distance label) */}
<item name="summaryBottomSheetSecondaryTextColor">@color/navigation_secondary_text</item>
</style>

Map route

You can use NavigationMapRoute to draw the route line on your map. Instantiate it with a MapView and MapboxMap, 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:


MapboxNavigation mapboxNavigation = new MapboxNavigation(...);
NavigationMapRoute navigationMapRoute = new NavigationMapRoute.Builder(...)
.withStyle(styleRes)
.build();

Here's an example that defines custom styles for the NavigationMapRoute:

<style name="CustomNavigationMapRoute">
{/* Color of the primary route */}
<item name="routeColor">@color/mapbox_navigation_route_layer_blue</item>
{/* Color of low traffic congestion */}
<item name="routeLowCongestionColor">@color/mapbox_navigation_route_layer_blue</item>
{/* Color of unknown traffic congestion on primary route */}
<item name="routeUnknownCongestionColor">@color/mapbox_navigation_route_layer_congestion_unknown</item>
{/* Color of moderate traffic congestion on primary route */}
<item name="routeModerateCongestionColor">@color/mapbox_navigation_route_layer_congestion_yellow</item>
{/* Color of heavy traffic congestion on primary route */}
<item name="routeHeavyCongestionColor">@color/mapbox_navigation_route_layer_congestion_heavy</item>
{/* Color of severe traffic congestion on primary route */}
<item name="routeSevereCongestionColor">@color/mapbox_navigation_route_layer_congestion_red</item>
{/* Color of primary route shield */}
<item name="routeShieldColor">@color/mapbox_navigation_route_shield_layer_color</item>
{/* Color of primary route traveled */}
<item name="routeLineTraveledColor">@color/mapbox_navigation_route_line_traveled_color</item>
{/* Color of primary route shield traveled */}
<item name="routeLineShieldTraveledColor">@color/mapbox_navigation_route_shield_line_traveled_color</item>
{/* Color of alternative route */}
<item name="alternativeRouteColor">@color/mapbox_navigation_route_alternative_color</item>
{/* Color of unknown traffic congestion on alternate route */}
<item name="alternativeRouteUnknownCongestionColor">@color/mapbox_navigation_route_alternative_congestion_unknown</item>
{/* Color of low traffic congestion on alternate route */}
<item name="alternativeRouteLowCongestionColor">@color/mapbox_navigation_route_alternative_color</item>
{/* Color of moderate traffic congestion on alternate route */}
<item name="alternativeRouteModerateCongestionColor">@color/mapbox_navigation_route_alternative_congestion_yellow</item>
{/* Color of heavy traffic congestion on alternate route */}
<item name="alternativeRouteHeavyCongestionColor">@color/mapbox_navigation_route_alternative_congestion_heavy</item>
{/* Color of severe traffic congestion on alternate route */}
<item name="alternativeRouteSevereCongestionColor">@color/mapbox_navigation_route_alternative_congestion_red</item>
{/* Color of alternative route shield */}
<item name="alternativeRouteShieldColor">@color/mapbox_navigation_route_alternative_shield_color</item>
{/* Scaling factor of primary route line */}
<item name="routeScale">1.0</item>
{/* Scaling factor of traffic on route line */}
<item name="routeTrafficScale">1.0</item>
{/* Scaling factor of alternative route line */}
<item name="alternativeRouteScale">1.0</item>
{/* Color of upcoming maneuver arrow */}
<item name="upcomingManeuverArrowColor">@color/mapbox_navigation_route_upcoming_maneuver_arrow_color</item>
{/* Color of upcoming maneuver arrow border */}
<item name="upcomingManeuverArrowBorderColor">@color/mapbox_navigation_route_upcoming_maneuver_arrow_border_color</item>
{/* Expression styling */}
<item name="roundedLineCap">true</item>
</style>

Route scaling

The route line scales at different zoom levels using the expressions feature of the Maps SDK. The default expression created for controlling the line scaling at various zoom levels looks like:

interpolate(
exponential(1.5f), zoom(),
stop(4f, product(literal(3f), literal(1))),
stop(10f, product(literal(4f), literal(1))),
stop(13f, product(literal(6f), literal(1))),
stop(16f, product(literal(10f), literal(1))),
stop(19f, product(literal(14f), literal(1))),
stop(22f, product(literal(18f), literal(1)))
)

For each stop, there are three values that determine the route line scaling. The first value is a zoom value. The second values is a literal value and the third value is a scale value. The literal value and the scale value are multiplied together.

These values are defined in the styles.xml file. You can override them to change the default scaling of the route line.

The route line's values in the styles.xml file look like:

<resources>
<string-array name="routeLineScaleStopsArray">
<item>4</item>
<item>10</item>
<item>13</item>
<item>16</item>
<item>19</item>
<item>22</item>
</string-array>

<string-array name="routeLineScaleMultiplierArray">
<item>3</item>
<item>4</item>
<item>6</item>
<item>10</item>
<item>14</item>
<item>18</item>
</string-array>

<string-array name="routeLineScalesArray">
<item>1</item>
<item>1</item>
<item>1</item>
<item>1</item>
<item>1</item>
<item>1</item>
</string-array>
</resources>

You can see that the values in the arrays above correspond to the expression example. The values at each position in the arrays will be combined to match the expression example above. There are arrays for the route line casing scale, the route line scale, and the traffic line scale. You can customize the scaling behavior of each line independently of the others. To customize the scaling behavior of the route line, override the style and provide arrays with your own values. The number of items in each of the arrays used for constructing the Expression.Stop should match.

As an example, to override the scaling of the traffic line to be half the (default) width of the route line, create a custom sytle, and override the default values like this:

<resources>
<string-array name="customRouteLineTrafficScalesArray">
<item>0.5</item>
<item>0.5</item>
<item>0.5</item>
<item>0.5</item>
<item>0.5</item>
<item>0.5</item>
</string-array>

<style name="CustomRouteStyle" parent="@style/MapboxStyleNavigationMapRoute">
<item name="routeLineTrafficScales">@array/customRouteLineTrafficScalesArray</item>
</style>
</resources>

Here you are creating an array of items with values of 0.5, which differs from the default array definition. The number of items is equal to the number of values in the default array and matches the number of items for the other scaling arrays for the traffic line. For each Expression.Stop in the expression, the scale value will be 0.5 instead of 1.

Also, the default array is overridden in a custom style defined in this example as CustomRouteStyle. The item name routeLineTrafficScales is the name of the default array, which is overridden with the @array/customRouteLineTrafficScalesArray defined above.

This demonstrates changing the scaling of the traffic line. All the values used in the expression for all three of the lines that make up the route line are configurable. This gives you a high degree of control over the expression used for the route line scaling. To understand the full power of expressions, read the expressions documentation to understand their full power.

Unknown traffic level color substitution

Often there can be cases in which the traffic congestion level is unknown for one or more sections of a route. You can configure those sections to be colored with the low traffic color rather than the unknown color for specified road classes.

To use the low traffic congestion color for parts of the route with unknown traffic congestion levels, create a string array in your styles.xml to show the road classes for which the substitution should occur.

<resources>
...
<string-array name="customTrafficBackFillRoadClasses">
<item>motorway</item>
</string-array>
...
</resources>

Then, create a custom style derived from the Mapbox style and override the trafficBackFillRoadClasses with your string array of road classes.

<style name="CustomRouteStyle" parent="@style/MapboxStyleNavigationMapRoute">
...
<item name="trafficBackFillRoadClasses">@array/customTrafficBackFillRoadClasses</item>
...
</style>

Find all the possible values for the road classes in our vector tiles documentation.

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

<com.mapbox.navigation.ui.NavigationView
android:id="@+id/navigationView"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:navigationLightTheme="@style/CustomNavigationViewLight"
app:navigationDarkTheme="@style/NavigationViewDark"
...
/>
Note
For the View to properly inflate, each style must either provide a value for every custom attribute or have a parent style (NavigationView). The default Mapbox style will be used if you do not provide a style for either of the light or dark theme attributes.

Here's an example that defines custom styles for the light theme:

<style name="CustomNavigationViewLight" parent="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>

{/* Other components */}
<item name="navigationViewDivider">#4882C6</item>
<item name="navigationViewRouteOverviewDrawable">#FAFAFA</item>
<item name="navigationViewDestinationMarker">@drawable/map_marker_light</item>
<item name="navigationViewLocationLayerStyle">@style/NavigationLocationLayerStyle</item>
</style>