Skip to main content

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 install @rnmapbox/maps

Configure @rnmapbox/maps

Update your podfile

Add the following to your ios/Podfile

// highlight-start
pre_install do |installer|
  $RNMapboxMaps.pre_install(installer)
end
// highlight-end

post_install do |installer|
// highlight-start
  $RNMapboxMaps.post_install(installer)
// highlight-end
  # ... 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...

Rebuild

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:

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

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

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

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": [
// highlight-start
      [
        "expo-location",
        {
          "locationWhenInUsePermission": "Show current location on map."
        }
      ]
// highlight-end
    ]
  }
}