Skip to main content

​
Overview

This guide covers how to use @rnmapbox/maps with Expo. The library includes a config plugin that automates most of the native configuration.
This package cannot be used in the Expo Go app because it requires custom native code. You must use a custom development build or bare workflow.

​
Prerequisites

  • Expo SDK 48 or higher
  • Node.js (v22.16.0 recommended)
  • Mapbox access token (see Setup Access Token)
  • EAS CLI (for custom development builds)

​
Installation

1

Install the package

Install @rnmapbox/maps using the Expo CLI:
expo install @rnmapbox/maps
This ensures you get a version compatible with your Expo SDK.
2

Add config plugin

Add the config plugin to your app.json, app.config.js, or app.config.ts:
{
  "expo": {
    "plugins": [
      [
        "@rnmapbox/maps",
        {
          "RNMapboxMapsVersion": "11.18.2"
        }
      ]
    ]
  }
}
3

Configure location permissions (Optional)

If you want to show the user’s current location, install and configure the expo-location plugin:
npx expo install expo-location
Then add it to your plugins array:
app.json
{
  "expo": {
    "plugins": [
      [
        "expo-location",
        {
          "locationWhenInUsePermission": "Show current location on map."
        }
      ],
      [
        "@rnmapbox/maps",
        {
          "RNMapboxMapsVersion": "11.18.2"
        }
      ]
    ]
  }
}
You can customize the locationWhenInUsePermission message to better fit your app’s use case.
4

Create a custom development build

Since this package requires custom native code, you need to create a custom development build:
npx expo prebuild
npx expo run:ios
# or
npx expo run:android
For more information, see Expo’s guide on adding custom native code.

​
Plugin Configuration Options

The @rnmapbox/maps config plugin accepts the following options:

​
RNMapboxMapsVersion

Override the native Mapbox SDK version: 
{
  "expo": {
    "plugins": [
      [
        "@rnmapbox/maps",
        {
          "RNMapboxMapsVersion": "11.18.2"
        }
      ]
    ]
  }
}
If you set a custom version, make sure to revisit it whenever you update @rnmapbox/maps. Using an incompatible version may cause build errors.

​
Usage Example

Once your custom build is ready, you can use Mapbox in your Expo app:
App.js
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox, { MapView } from '@rnmapbox/maps';

// Set your Mapbox access token
Mapbox.setAccessToken('<YOUR_ACCESSTOKEN>');

const App = () => {
  return (
    <View style={styles.page}>
      <View style={styles.container}>
        <MapView style={styles.map} />
      </View>
    </View>
  );
};

export default App;

const styles = StyleSheet.create({
  page: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  container: {
    height: 300,
    width: 300,
  },
  map: {
    flex: 1,
  },
});

​
Bare Workflow

If you’re using the bare workflow, you can follow the manual setup guides instead:

​
Troubleshooting

​
”Expo Go” compatibility error

The library requires custom native code and cannot run in Expo Go. You must create a custom development build using expo prebuild or EAS Build.

​
Build fails after adding plugin

  1. Clear your build cache: 
    npx expo prebuild --clean
  2. Rebuild your app: 
    npx expo run:ios
# or
npx expo run:android

​
Changes to config plugin not taking effect

After modifying the config plugin settings:
  1. Run npx expo prebuild --clean to regenerate native files
  2. Rebuild your app

​
Next Steps

After completing the Expo setup:

Build docs developers (and LLMs) love

Get started for freeTalk to us