Skip to main content

Choose an approach

Join the Mapbox Developers Discord Communityarrow-right
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.17.13, in the Navigation SDK documentation.

The Mapbox Navigation SDK's core logic and UI elements provide different ways to create a turn-by-turn navigation experience. Various approaches have their own benefits and limitations. This guide will walk you through the options and provide some guidance on how to get started with each.

As a reminder and as explained in the Navigation SDK overview, the core part of the Navigation SDK provides navigational logic such as route requesting and determining when the device is off-route. The UI part of the Navigation SDK provides pre-built UI elements.

Drop-in UI​

If the only map in your application is used for a turn-by-turn navigation experience, Mapbox offers a more customizable approach: the Navigation UI SDK's NavigationView.

check Benefits:

  • Broad set of customizable options
  • Predefined UI elements

close Limitations:

  • Limited options for modifying NavigationView layout elements
  • No seamless access to the MapView's instance

Add the NavigationView​

The NavigationView class extends the Android View class. NavigationView is like the Maps SDK's MapView class in creating a map and customizing it. The difference is that the navigation functionality is already built in and does not have to be added via the core Navigation SDK. After initialization of NavigationView, the startNavigation(NavigationViewOptions options) method can be called to start the turn-by-turn navigation experience on the initialized map.

example
NavigationView

Display the NavigationView

chevron-right

Collection of standalone components​

If you want to build a completely customizable turn-by-turn experience, you can use the core Navigation SDK to build standalone navigation components on top of the Maps SDK for Android's MapView. This approach may also be appropriate if you'd like to integrate components of turn-by-turn navigation into an existing mapping application. For example, you could use the Navigation SDK to request a DirectionsRoute and use the Maps SDK to draw a two-color gradient line that follows the same path as the DirectionsRoute, but you don't plan on providing turn-by-turn instructions.

check Benefits:

  • Completely customizable
  • Do Navigation on the same MapView that is used for other tasks

close Limitations:

  • No out-of-the-box solution
  • Layout and function need manual implementation

Build a collection of components​

The interplay of the Maps SDK's MapView and the navigation logic that's provided by the Navigation SDK's MapboxNavigation class, creates the most customizable approach to turn-by-turn navigation experiences. This combination brings together the MapView class, which allows for embedding highly customizable maps, and the full flexibility of the MapboxNavigation class. This allows you to customize every detail of the navigation experience without having to build it completely from scratch (using Mapbox APIs directly).

  • Map: You will need to include a MapView element in your project's layout XML file. You can read more about how to customize MapView in the Maps SDK for Android documentation.
  • Route: Display a route on the map (Navigation UI SDK's NavigationMapRoute standalone component can be used).
  • Route events: A RouteProgressObserver can be attached, which implements callbacks related to route progress. An OffRouteObserver can also be attached.
  • Instructions: To include an InstructionView panel that displays instructions as needed along the route, you will need to include an InstructionView element in your project's layout XML file. This panel can also include navigation icons that show what maneuver to take next. Any icons can be used, but Mapbox offers an open set of icons.
  • Route summary: Most turn-by-turn navigation experiences also include a way to view a list of all instructions along with a summary of the distance and time required to complete the route (Navigation UI SDK's SummaryBottomSheet standalone component can be used).
  • Feedback: You should include a mechanism for users to provide feedback (Navigation UI SDK's FeedbackButton and FeedbackBottomSheet standalone components can be used).
  • Voice: You should include instructions for the NavigationSpeechPlayer to read out loud (Navigation UI SDK's VoiceInstructions can be used).
example
Basic Navigation + Maps SDK integration

Shows how to combine the Maps SDK with only the Navigation SDK and no Navigation UI SDK code of any kind.

chevron-right
Join the Mapbox Developers Discord Communityarrow-right