Navigation

const Navigation: object;

Defined in: src/Navigation.ts:80

The headless navigation API: route requests, the app's single guidance session, and its events. It's also the default export.

Type Declaration

addArriveListener()

addArriveListener(listener: (event: ArriveEvent) => void): EventSubscription;

Called when guidance reaches a waypoint, the final destination included.

Parameters

Parameter	Type
listener	(event: ArriveEvent) => void

Returns

EventSubscription

addCameraStateListener()

addCameraStateListener(listener: (state: CameraState) => void): EventSubscription;

Called whenever the camera state changes, whether from JS, guidance or a map gesture.

Parameters

Parameter	Type
listener	(state: CameraState) => void

Returns

EventSubscription

addCarPlayConnectionListener()

addCarPlayConnectionListener(listener: (connected: boolean) => void): EventSubscription;

Called when a CarPlay screen connects or disconnects.

Parameters

Parameter	Type
listener	(connected: boolean) => void

Returns

EventSubscription

addLocationListener()

addLocationListener(listener: (event: LocationEvent) => void): EventSubscription;

The location snapped to the road or route, with its speed limit and road name, during free drive and guidance.

Parameters

Parameter	Type
listener	(event: LocationEvent) => void

Returns

EventSubscription

addOffRouteListener()

addOffRouteListener(listener: (offRoute: boolean) => void): EventSubscription;

Called with true when the user leaves the route, then with false once guidance follows a route again.

Parameters

Parameter	Type
listener	(offRoute: boolean) => void

Returns

EventSubscription

addRouteChangeListener()

addRouteChangeListener(listener: (event: RouteChangeEvent) => void): EventSubscription;

Called when guidance switches to another route on its own. Every listener gets the same new Route; the previous one stays valid until released.

Parameters

Parameter	Type
listener	(event: RouteChangeEvent) => void

Returns

EventSubscription

addRouteProgressListener()

addRouteProgressListener(listener: (event: RouteProgressEvent) => void): EventSubscription;

Called as guidance moves along the route, from the headless API and <NavigationView> alike. Events already on their way to JS can still arrive after stopNavigation.

Parameters

Parameter	Type
listener	(event: RouteProgressEvent) => void

Returns

EventSubscription

addSessionStateListener()

addSessionStateListener(listener: (state: SessionState) => void): EventSubscription;

Called when the session goes idle, starts free drive or starts guidance, whether from JS, <NavigationView> or the car screen.

Parameters

Parameter	Type
listener	(state: SessionState) => void

Returns

EventSubscription

addVoiceInstructionListener()

addVoiceInstructionListener(listener: (event: VoiceInstructionEvent) => void): EventSubscription;

Called when an instruction is due, whether or not the SDK speaks it; for apps doing their own text to speech.

Parameters

Parameter	Type
listener	(event: VoiceInstructionEvent) => void

Returns

EventSubscription

advanceToNextLeg()

advanceToNextLeg(): void;

Ends the current leg and guides to the next waypoint, e.g. to skip a stop, or after an arrival with setAutoAdvanceLegs off. Does nothing on the last leg or without active guidance. Away from the waypoint, guidance reroutes from where it is; simulated guidance jumps to the start of the new leg and reroutes again.

Returns

void

getCameraState()

getCameraState(): CameraState;

The camera state of navigation maps, see setCameraState.

Returns

CameraState

getDefaultDistanceUnit()

getDefaultDistanceUnit(): DistanceUnit;

The unit the device's region and measurement settings call for, which the native views use.

Returns

DistanceUnit

getRouteStats()

getRouteStats(): RouteStats;

Counts of native routes, for leak checks.

Returns

RouteStats

getSdkVersion()

getSdkVersion(): string;

Version of the native Mapbox Navigation SDK linked into the app.

Returns

string

getSessionState()

getSessionState(): SessionState;

The state of the navigation session, see addSessionStateListener.

Returns

SessionState

isCarPlayConnected()

isCarPlayConnected(): boolean;

Whether a CarPlay screen shows the navigation session; see the carPlay option of the Expo config plugin. Always false on Android.

Returns

boolean

isVoiceMuted()

isVoiceMuted(): boolean;

Whether voice instructions are muted, by setVoiceMuted or <NavigationView>'s mute button.

Returns

boolean

previewRoute()

previewRoute(route: Route | null): void;

Shows route on navigation maps until guidance starts or stopNavigation is called; null removes it. Throws if route was released.

Parameters

Parameter	Type
route	Route | null

Returns

void

registerCarPlayRoot()

registerCarPlayRoot(component: ComponentType): void;

Sets the component iOS keeps mounted while CarPlay is connected, in a React root of its own that draws nothing; render CarMap in it. When CarPlay launches the app without its phone UI, this root starts React Native. Needs the Expo plugin's carPlayRoot option (or RNMBXNavigationCarPlayRoot.reactNativeFactory set in the app delegate) and React Native 0.79+. Call it in the app's entry file, next to registerRootComponent, as CarPlay looks the root up before anything else loads. Android ignores it.

Parameters

Parameter	Type
component	ComponentType

Returns

void

requestMatchedRoutes()

requestMatchedRoutes(options: MatchedRouteRequestOptions): Promise<RouteResponse>;

Snaps options.coordinates to roads with the Mapbox Map Matching API and resolves with a route along them, for guiding a path the app defines, such as a tour or a delivery run. The route works with previewRoute and startActiveGuidance like one from requestRoutes; alternatives is always empty. Neither SDK reroutes a matched route: guidance reports going off route and waits for the user to return to it.

Rejects without a request if the options break the Map Matching API's limits, and with code: 'no_single_match' if the API can only match the coordinates as several disconnected pieces. On Android this uses requestMapMatching, which the SDK marks @ExperimentalPreviewMapboxNavigationAPI, so it may change in minor releases.

Parameters

Parameter	Type
options	MatchedRouteRequestOptions

Returns

Promise<RouteResponse>

requestRoutes()

requestRoutes(options: RouteRequestOptions): Promise<RouteResponse>;

Requests routes through options.waypoints. The routes hold native memory: release() the ones you don't keep. Rejects with code: 'invalid_options' with fewer than two waypoints, an option the profile doesn't support, or a value out of range.

Parameters

Parameter	Type
options	RouteRequestOptions

Returns

Promise<RouteResponse>

setAccessToken()

setAccessToken(accessToken: string): void;

Must be called before any request; navigation is billed to this token.

Parameters

Parameter	Type
accessToken	string

Returns

void

setAutoAdvanceLegs()

setAutoAdvanceLegs(enabled: boolean): void;

Whether guidance moves on to the next leg by itself once it arrives at a waypoint, which is the default. When off, guidance stays at the waypoint, simulated guidance included, until advanceToNextLeg; arrivals are still reported to addArriveListener. Turning it on while guidance waits at a waypoint doesn't move on; call advanceToNextLeg.

Parameters

Parameter	Type
enabled	boolean

Returns

void

setCameraState()

setCameraState(state: CameraState): void;

Camera of every navigation map (<MapView mapViewImpl={NAVIGATION_MAP_VIEW_IMPL}>). idle hands the camera back to the user's gestures and @rnmapbox/maps Camera. Guidance switches it to following; a pan, zoom, rotate or pitch gesture on any navigation map switches it to idle. Use addCameraStateListener to follow those changes.

Parameters

Parameter	Type
state	CameraState

Returns

void

setKeepScreenOn()

setKeepScreenOn(keepScreenOn: boolean): void;

Whether active guidance, <NavigationView>'s included, keeps the screen on. On by default. When guidance stops, the app's own idle timer or keep screen on setting is restored. Turn it off if the app manages that itself.

Parameters

Parameter	Type
keepScreenOn	boolean

Returns

void

setRerouteEnabled()

setRerouteEnabled(enabled: boolean): void;

Whether guidance requests a new route when the user leaves a route from requestRoutes. Defaults to true. Matched routes from requestMatchedRoutes are never rerouted.

Android applies it at once, also during guidance. iOS reads it only when the navigation session is created, which happens on the first route request or guidance start, so call it before those, e.g. next to setAccessToken. On iOS a later call that changes the value has no effect and logs a warning.

Parameters

Parameter	Type
enabled	boolean

Returns

void

setSimulationSpeed()

setSimulationSpeed(multiplier: number): void;

Speed of simulated guidance relative to the route's expected speeds, e.g. 2 drives twice as fast; the default is 1. Applies to the running and later simulations. Simulated locations keep reporting the route's speed, not multiplied. Higher speeds can make guidance go off-route at sharp turns and reroute, and on Android the simulation doesn't follow reroutes. Throws unless multiplier is positive.

Parameters

Parameter	Type
multiplier	number

Returns

void

setVoiceMuted()

setVoiceMuted(muted: boolean): void;

Mutes the SDK's voice instructions for all guidance, including <NavigationView>.

Parameters

Parameter	Type
muted	boolean

Returns

void

setVoiceVolume()

setVoiceVolume(volume: number): void;

Volume of the SDK's voice instructions, from 0 to 1, relative to the device's media volume; clamped to that range. Independent of setVoiceMuted. On iOS, it doesn't apply to instructions spoken by the system voice, which the SDK falls back to when the Mapbox voice is unavailable, e.g. offline. Throws if volume is NaN.

Parameters

Parameter	Type
volume	number

Returns

void

startActiveGuidance()

startActiveGuidance(route: Route, options?: StartActiveGuidanceOptions): Promise<void>;

Starts active guidance along route, replacing any active guidance, and switches the camera to following. Rejects if route was released. Guidance keeps its own reference to the native route until stopNavigation, so route can be released at any time.

Parameters

Parameter	Type
route	Route
options?	StartActiveGuidanceOptions

Returns

Promise<void>

startFreeDrive()

startFreeDrive(options?: StartFreeDriveOptions): Promise<void>;

Starts free drive: the location is matched to the road without a route, so addLocationListener reports the road name and speed limit, and navigation maps show the puck. It runs until stopNavigation or a JS reload; this API never starts it on its own.

During guidance it ends the guidance and keeps the session in free drive. After simulated guidance, the simulated device stays where guidance stopped unless simulatedLocation moves it.

Free drive trips are billed by Mapbox like guidance trips, see Navigation SDK pricing.

Rejects with code: 'location_permission' if the app has no location permission and simulatedLocation isn't set; request the permission first.

Parameters

Parameter	Type
options?	StartFreeDriveOptions

Returns

Promise<void>

stopNavigation()

stopNavigation(): void;

Stops guidance or free drive and removes the route from navigation maps. The camera switches to idle and eases back to north-up.

Returns

void