Note that those instructions applies to the 10.1 version. Please visit the installation guide for the older 10.0.15 which can be found on the github v10.0 branch of the project

Configure credentials

Before installing @rnmapbox/maps you'll need to get the proper credentials. You'll need two tokens:

• Secret access token with (Downloads:Read) scope to download iOS and Android SDK from mapbox. The secret token starts with sk.ey
• Public token to use as accessToken when running the app. The public token starts with pk.ey

See Configure Credential on mapbox.com for details.

Install

NPM

npm install @rnmapbox/maps

Yarn

yarn add @rnmapbox/maps

Expo

expo install @rnmapbox/maps

Configure @rnmapbox/maps

iOS

Update your podfile

Add the following to your ios/Podfile

pre_install do |installer|
  $RNMapboxMaps.pre_install(installer)
end

post_install do |installer|
  $RNMapboxMaps.post_install(installer)
  # ... other post install hooks
end

Verify .netrc

Make sure your .netrc is configured with your secret access token, as described by the mapbox docs. To verify execute:

grep -A 4 api.mapbox.com ~/.netrc

This should output something like:

machine api.mapbox.com
  login mapbox
  password sk.ey...

Android

Adding mapbox maven repo

Add the following to your android/build.gradle, into the section allprojects/repositories

// android/build.gradle

allprojects {
    repositories {
        maven {
            url 'https://api.mapbox.com/downloads/v2/releases/maven'
            authentication {
                basic(BasicAuthentication)
            }
            credentials {
                // Do not change the username below.
                // This should always be `mapbox` (not your username).
                username = 'mapbox'
                // Use the secret token you stored in gradle.properties as the password
                password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
            }
        }
    }
}

Verify MAPBOX_DOWNLOADS_TOKEN in gradle.properties

Make sure your global .gradle-properties is configured with your secret access token, as described by the mapbox docs. To verify execute:

grep -R MAPBOX_DOWNLOADS_TOKEN ~/.gradle/gradle.properties

This should output something like:

/Users/foo/.gradle/gradle.properties:MAPBOX_DOWNLOADS_TOKEN=sk.ey...

Expo

Plugin configuration

Set RNMapboxMapsDownloadToken to your secret token. See the credentials instructions on mapbox.com.

Add RNMapboxMapsDownloadToken to the @rnmapbox/maps config plugin in the plugins array of your app.{json,config.js,config.ts}:

{
  "expo": {
    "plugins": [
      [
        "@rnmapbox/maps",
        {
          "RNMapboxMapsDownloadToken": "sk.ey.."
        }
      ]
    ]
  }
}

Rebuild

iOS

(cd ios && pod install)
npm run ios

Android

npm run android

Expo

React Native Mapbox Maps cannot be used in the "Expo Go" app, because it requires custom native code.

Next, if you are not using EAS Build then you must rebuild your app as described in the "Adding custom native code" guide to include the config plugin changes. If this command isn't run, you'll not be able use @rnmapbox/maps.

expo prebuild --clean

Using V11

@rnmapbox 10.1 supports both 10.16.* and 11.0.* versions, but defaults to 10.16.*. To use 11.0.* please configure according to your platform:

iOS

Add the following to your ios/Podfile

$RNMapboxMapsVersion = '= 11.0.0'

Since Mapbox Maps 11 requires ios 12.4 or later, you might need to update deployment target line in your ios/Podfile:

platform :ios, '12.4' # change to minimum 12.4

Android

Set RNMapboxMapsVersion in android/build.gradle > buildscript > ext section

buildscript {
    ext {
        RNMapboxMapsVersion = '11.0.0'
    }
}

Expo

Add RNMapboxMapsVersion to the @rnmapbox/maps config plugin to the plugins array of your app.{json,config.js,config.ts}:

{
  "expo": {
    "plugins": [
      [
        "@rnmapbox/maps",
        {
          ...
          "RNMapboxMapsVersion": "11.0.0"
        }
      ]
    ]
  }
}

Advanced - using non default version

It's possible to overwrite the native SDK version with RNMapboxMapsVersion. But you have to revise it when upgrading @rnmapbox/maps as future @rnmapbox/maps releases might not support he version you set today.

Follow the instructions above on using v11, just use 10.* version you'd like.

Configure permissions for location access

iOS

If you want to show the location puck on the map with the LocationPuck component, you'll need to add the following property to your Info.plist (see Mapbox iOS docs for more info):

 <key>NSLocationWhenInUseUsageDescription</key>
 <string>Show current location on map.</string>

Android

If you plan to display the user's location on the map or get the user's location information you will need to add the ACCESS_COARSE_LOCATION permission in your application's AndroidManifest.xml. You also need to add ACCESS_FINE_LOCATION permissions if you need access to precise location. You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager. See Mapbox android install guides for more information.

android/app/src/main/AndroidManifest.xml

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

Expo

If you want to show the location puck on the map with the LocationPuck component, you can use the expo-location plugin to configure the required NSLocationWhenInUseUsageDescription property. Install the plugin with npx expo install expo-location and add its config plugin to the plugins array of your app.{json,config.js,config.ts}:

{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "locationWhenInUsePermission": "Show current location on map."
        }
      ]
    ]
  }
}