Skip to main content

Maps for navigation

Join the Mapbox Developers Discord Communityarrow-right

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 for the entire navigation experience end to end. PreviewViewController provides everything you need for free-drive navigation and route previewing, while NavigationViewController covers turn-by-turn navigation. PreviewViewController starts by displaying the user’s current location on top of a map using the Mapbox Navigation Day v1 style, but you can show routes for the user to select. Once the user has selected a route, NavigationViewController follows the user’s current location as they move along the route line.

Read more about what's included in the PreviewViewController for the free-drive experience in the Free-drive navigation: User Interface guide. You can find more information about the turn-by-turn experience using NavigationViewController 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()

view.addSubview(navigationMapView)

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.

Beware that certain views provided by the Navigation SDK for iOS are used on both iOS and CarPlay. This means that such views should be styled independently for each platform. Views that are used on both iOS and CarPlay include (but not limited to):

Subclass DayStyle, and choose from a variety of visual properties to customize:

class CustomDayStyle: DayStyle {

    required init() {
        super.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() {
        super.apply()

        // Specify color for iPad.
        WayNameView.appearance(for: UITraitCollection(userInterfaceIdiom: .pad)).backgroundColor = .red

        // Specify color for iPhone (different colors for Light and Dark user interface styles are used).
        if #available(iOS 12.0, *) {
            let lightStylePhoneTraitCollection = UITraitCollection(traitsFrom: [
                UITraitCollection(userInterfaceIdiom: .phone),
                UITraitCollection(userInterfaceStyle: .light),
            ])

            WayNameView.appearance(for: lightStylePhoneTraitCollection).backgroundColor = .blue

            let darkStylePhoneTraitCollection = UITraitCollection(traitsFrom: [
                UITraitCollection(userInterfaceIdiom: .phone),
                UITraitCollection(userInterfaceStyle: .dark),
            ])

            WayNameView.appearance(for: darkStylePhoneTraitCollection).backgroundColor = .yellow
        }

        // Specify color for CarPlay (different colors for Light and Dark user interface styles are used).
        if #available(iOS 12.0, *) {
            let lightStyleCarPlayTraitCollection = UITraitCollection(traitsFrom: [
                UITraitCollection(userInterfaceIdiom: .carPlay),
                UITraitCollection(userInterfaceStyle: .light),
            ])

            WayNameView.appearance(for: lightStyleCarPlayTraitCollection).backgroundColor = .green

            let darkStyleCarPlayTraitCollection = UITraitCollection(traitsFrom: [
                UITraitCollection(userInterfaceIdiom: .carPlay),
                UITraitCollection(userInterfaceStyle: .dark),
            ])

            WayNameView.appearance(for: darkStyleCarPlayTraitCollection).backgroundColor = .gray
        }
    }
}

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() {
        super.init()

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

    override func apply() {
        super.apply()

        // `BottomBannerView` is not used on CarPlay, so styling is only provided for iPhone and iPad.
        BottomBannerView.appearance(for: UITraitCollection(userInterfaceIdiom: .phone)).backgroundColor = .purple
        BottomBannerView.appearance(for: UITraitCollection(userInterfaceIdiom: .pad)).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.

Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?