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 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.
Navigation map view
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):
NavigationMapView
WayNameView
SpeedLimitView
InstructionLabel
PrimaryLabel
SecondaryLabel
WayNameLabel
ExitView
GenericRouteShield
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.