Maps for navigation

While applications using the Mapbox Navigation SDK for iOS don't have to include a map, many use cases will require maps to provide an appropriate navigation experience to your users. After you install and initialize the Navigation SDK, this guide will help you understand how the Navigation SDK uses the Mapbox Maps SDK and what you need to do to include a map in your application.

By default, the Navigation SDK comes with access to the Mapbox Maps SDK for iOS to display routes on a map and show the user's location on the map throughout their trip to provide both navigation-related context and nearby places that may be of interest to the driver.

Add a map

Include a map in your application for turn-by-turn or free-drive navigation.

Drop-in UI

The Navigation SDK for iOS offers a complete drop-in UI, NavigationViewController, for turn-by-turn navigation experiences. By default, NavigationViewController includes a map using the Mapbox Navigation Day v1 style, a puck displaying the user's current location, and a route line.

Read more about what's included in the NavigationViewController for turn-by-turn experiences in the Turn-by-turn navigation: User Interface guide.

You can use the NavigationMapView class directly if you are building a free-drive navigation experience, displaying a route preview on a map, or building any custom map UI with the Navigation SDK.

NavigationMapView is a navigation-specific wrapper around the Mapbox Maps SDK's MapView class that provides convenience functions for visualizing the user’s current location and Route objects from the Mapbox Directions API as route lines.

navigationMapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
navigationMapView.userLocationStyle = .puck2D()


Set up the map camera:

let navigationViewportDataSource = NavigationViewportDataSource(navigationMapView.mapView)
navigationViewportDataSource.followingMobileCamera.zoom = 15.0
navigationMapView.navigationCamera.viewportDataSource = navigationViewportDataSource

To display a route preview on a map before beginning turn-by-turn navigation, use NavigationMapView's showcase method, which adds routes and waypoints to map and sets the camera to encompass the route.

// Showcase the route and destination waypoint, and set camera
navigationMapView.showcase(routes, animated: true)

Read more about building a free-drive experience in the Free-drive navigation guide.

Customize the map style

Although it is possible to customize the map view’s style directly, you should customize it through a UI style to make sure consistency with the rest of the UI, especially after the UI switches between day and night appearances. Subclass DayStyle, and choose from a variety of visual properties to customize:

class CustomDayStyle: DayStyle {
    required init() {

        // Use a custom map style.
        mapStyleURL = URL(string: StyleURI.satelliteStreets.rawValue)!
        previewMapStyleURL = URL(string: StyleURI.satelliteStreets.rawValue)!

        // Specify that the style should be used during the day.
        styleType = .day
    override func apply() {

        // Begin styling the UI
        BottomBannerView.appearance().backgroundColor = .orange

You can provide a custom night style that will be used at night and while the user travels through a tunnel.

class CustomNightStyle: NightStyle {

    required init() {

        // Specify that the style should be used at night.
        styleType = .night

    override func apply() {

        // Begin styling the UI
        BottomBannerView.appearance().backgroundColor = .purple

Then, initialize NavigationViewController with these styles.

let navigationOptions = NavigationOptions(styles: [CustomDayStyle(), CustomNightStyle()])
let navigationViewController = NavigationViewController(for: route, routeIndex: 0, routeOptions: routeOptions, navigationOptions: navigationOptions)

Customize map behavior

Because the Navigation SDK includes the full Maps SDK as a dependency, you can completely customize when and how maps are used in your application. For more information on how the Maps SDK works, see the Maps SDK v10 documentation.