Note that those instructions applies to the 10.2.* versions of @rnmapbox/maps.

Configure credentials

Before installing @rnmapbox/maps you'll need to get your Mapbox access token.

To grab your token, open up a browser and go to your account's tokens page: https://console.mapbox.com/account/access-tokens/

On the top of your token list, copy your Default Public Token. The public token starts with pk.ey.

For more details, see Configure Credentials on mapbox.com.

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

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'
        }
    }
}

Expo

Plugin configuration

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

{
  "expo": {
    "plugins": [
      "@rnmapbox/maps"
    ]
  }
}

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

Customizing Mapbox Version

@rnmapbox/maps 10.2 defaults to Mapbox Maps SDK 11.0.*.

Note: Mapbox Maps SDK v10 is now deprecated. We recommend using v11 for new projects and upgrading existing projects to v11.

Using V10 (Deprecated)

If you need to use the deprecated 10.16.* version, you can configure it according to your platform:

iOS

Add the following to your ios/Podfile

$RNMapboxMapsVersion = '~> 10.16.0'

Android

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

buildscript {
    ext {
        RNMapboxMapsVersion = '10.16.4'
    }
}

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": "10.16.4"
        }
      ]
    ]
  }
}

Advanced - using non default version

It's possible to overwrite the native SDK version with RNMapboxMapsVersion. However, you should revise this when upgrading @rnmapbox/maps as future releases might not support the version you set.

To use a specific v11 version, follow the instructions above for customizing the Mapbox version, specifying your desired 11.* version (e.g., 11.0.0, 11.1.0, etc.).

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."
        }
      ]
    ]
  }
}