Skip to main content

Install @rnmapbox/navigation

Set up @rnmapbox/maps first, following its install guide. @rnmapbox/navigation needs @rnmapbox/maps >=10.3.16 <10.4.0 and React Native 0.79+ with the New Architecture. See Versions for older releases.

Install​

Pin @rnmapbox/maps to the 10.3 line, so a later 10.4 outside the supported range isn't picked up:

npm install @rnmapbox/navigation @rnmapbox/maps@~10.3.16

Configure @rnmapbox/navigation​

The Navigation SDK v3 is only distributed as a Swift package. @rnmapbox/navigation links it, and through it MapboxMaps, into the app. @rnmapbox/maps must only compile against that MapboxMaps, otherwise the app links two copies of MapboxMaps and fails with duplicate symbols.

Update your podfile​

$RNMapboxMapsSwiftPackageManager = { link: false }

target 'YourApp' do
  # ...
  pre_install do |installer|
    $RNMapboxMaps.pre_install(installer)
  end

  post_install do |installer|
    react_native_post_install(installer, ...)
    $RNMapboxMaps.post_install(installer)
  end
end

pod install adds MapboxCommon, MapboxCoreMaps, MapboxNavigationNative and Turf to the frameworks CocoaPods embeds.

Info.plist​

Add NSLocationWhenInUseUsageDescription, and audio to UIBackgroundModes: the Navigation SDK's voice controller asserts on it in debug builds on any guidance start, even with voice muted.

Versions​

Set these before use_native_modules! if you need to:

# Navigation SDK version, defaults to 3.33.0. Nav 3.N pins Maps 11.N.
$RNMapboxNavigationVersion = '3.33.0'
# Don't add the Swift package; add mapbox-navigation-ios (products MapboxNavigationCore and
# MapboxNavigationUIKit) yourself.
$RNMapboxNavigationSwiftPackageManager = 'manual'

@rnmapbox/maps' package requirement comes from $RNMapboxMapsVersion (default ~> 11.33.0) and must be compatible with the Maps version the Navigation SDK pins, otherwise Xcode reports a package resolution error. With a newer Navigation SDK, set $RNMapboxMapsVersion = '= 11.N.x' to match.

Access token​

Pass your public access token to both libraries before requesting routes. Navigation is billed to this token.

import Mapbox from '@rnmapbox/maps';
import Navigation from '@rnmapbox/navigation';

Mapbox.setAccessToken('pk....');
Navigation.setAccessToken('pk....');

Location permission​

The app must have runtime location permission before guidance on the device's location (simulate off). Simulated guidance doesn't need it.

  • Android: the Navigation SDK's manifest declares the location permissions, but the app has to request them at runtime, e.g. with Mapbox.requestAndroidLocationPermissions() from @rnmapbox/maps, which resolves to whether they were granted. It throws on iOS.
  • iOS: set NSLocationWhenInUseUsageDescription (the Expo plugin sets it). The Navigation SDK asks for when-in-use authorization itself; ask from your own UI first, e.g. with expo-location, if you want to explain why.
import { Platform } from 'react-native';
import Mapbox from '@rnmapbox/maps';
import Navigation, { type Route } from '@rnmapbox/navigation';

async function startGuidance(route: Route) {
  if (
    Platform.OS === 'android' &&
    !(await Mapbox.requestAndroidLocationPermissions())
  ) {
    return; // Denied: tell the user why navigation needs their location.
  }
  await Navigation.startActiveGuidance(route, { simulate: false });
}

See Configure permissions for location access in the @rnmapbox/maps install guide for the manifest and Info.plist entries.

Next: Getting started.