Set up @rnmapbox/maps first, following its install guide. @rnmapbox/navigation needs @rnmapbox/maps 10.3.11 or newer.

Install

NPM

npm install @rnmapbox/navigation @rnmapbox/maps

Yarn

yarn add @rnmapbox/navigation @rnmapbox/maps

Configure @rnmapbox/navigation

iOS

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. For <NavigationView>, also add audio to UIBackgroundModes: the SDK's voice controller asserts on it in debug builds.

Versions

Set these before use_native_modules! if you need to:

# Navigation SDK version, defaults to 3.23.1. Nav 3.N pins Maps 11.N.
$RNMapboxNavigationVersion = '3.23.1'
# 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.23.1) 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.

Android

Adding mapbox maven repo and versions

Add the Mapbox Maven repository, the same one @rnmapbox/maps uses, and set the Maps version the Navigation SDK pins:

// android/build.gradle
buildscript {
    ext {
        // Nav 3.23.1 pins Maps 11.23.1. Both packages must resolve the same Maps.
        RNMapboxMapsVersion = '11.23.1'
        // Optional, defaults to 3.23.1.
        RNMapboxNavigationVersion = '3.23.1'
    }
}

allprojects {
    repositories {
        maven { url 'https://api.mapbox.com/downloads/v2/releases/maven' }
    }
}

@rnmapbox/navigation adds a strict constraint on the Maps version its Navigation SDK is built against, so a different RNMapboxMapsVersion fails dependency resolution instead of silently mixing versions.

With targetSdkVersion 35 or higher both libraries use the -ndk27 artifacts (16 KB pages). Keep targetSdkVersion in the root project ext, where both libraries read it.

Expo

There's no Expo config plugin in the current release. Use a development build, as Expo Go doesn't include the native SDKs, and apply the iOS and Android setup yourself.

A config plugin is in progress in rnmapbox/navigation#7.

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....');

Next: Getting started.