Documentation Index Fetch the complete documentation index at: https://mintlify.com/rnmapbox/maps/llms.txt
Use this file to discover all available pages before exploring further.
Installation This guide will help you install and configure @rnmapbox/maps for iOS, Android, and Expo projects.
Prerequisites Step 1: Install the Package Install @rnmapbox/maps using your preferred package manager:
npm install @rnmapbox/maps
Choose your platform for detailed setup instructions:
iOS Configuration After installing the package, you need to configure your iOS project. Update Podfile Add the following hooks to your ios/Podfile: pre_install do | installer | $RNMapboxMaps . pre_install (installer) # ... other pre install hooks end post_install do | installer | $RNMapboxMaps . post_install (installer) # ... other post install hooks end
Install Pods Navigate to the iOS directory and install dependencies: Add Location Permissions (Optional) If you want to show the user’s location with the UserLocation or LocationPuck component, add location permissions to your ios/Info.plist: < key > NSLocationWhenInUseUsageDescription </ key > < string > Show current location on map. </ string >
Custom Mapbox Version (Optional) To use a specific Mapbox SDK version, add this to the top of your Podfile: $RNMapboxMapsVersion = '= 11.18.2'
If you set a custom version, make sure to update it when upgrading @rnmapbox/maps to avoid compatibility issues.
Android Configuration Configure your Android project to use Mapbox Maps SDK v11. Add Mapbox Maven Repository Add the Mapbox Maven repository to your android/build.gradle file: allprojects { repositories { // ... other repos maven { url 'https://api.mapbox.com/downloads/v2/releases/maven' } // ... more repos } }
Mapbox has removed the authentication requirement for downloads, so MAPBOX_DOWNLOADS_TOKEN is no longer needed.
Custom Mapbox Version (Optional) To specify a custom Mapbox SDK version, add this to android/build.gradle in the buildscript > ext section: buildscript { ext { RNMapboxMapsVersion = '11.18.2' } }
If you set a custom version, make sure to revisit it when updating @rnmapbox/maps to avoid build errors.
Troubleshooting: libc++_shared.so Conflicts If you encounter errors about duplicate libc++_shared.so files, add this to your android/app/build.gradle: android { packagingOptions { pickFirst 'lib/x86/libc++_shared.so' pickFirst 'lib/x86_64/libc++_shared.so' pickFirst 'lib/arm64-v8a/libc++_shared.so' pickFirst 'lib/armeabi-v7a/libc++_shared.so' } }
Expo Configuration This package cannot be used in the “Expo Go” app because it requires custom native code.
Install with Expo CLI expo install @rnmapbox/maps
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" } ] ] } }
Add Location Permissions (Optional) To use the user’s location, install and configure expo-location: npx expo install expo-location
Add it to your plugins array: { "expo" : { "plugins" : [ [ "expo-location" , { "locationWhenInUsePermission" : "Show current location on map." } ] ] } }
Rebuild Your App After configuration, rebuild your app: npx expo prebuild npx expo run:ios # or npx expo run:android
Custom Mapbox Version You can override the native SDK version in the plugin configuration: { "expo" : { "plugins" : [ [ "@rnmapbox/maps" , { "RNMapboxMapsVersion" : "11.18.2" } ] ] } }
Step 3: Verify Installation Verify your installation by running your app:
npm run ios # or yarn ios
Troubleshooting iOS: Pod Install Fails After Upgrade If you see an error like could not find compatible versions for pod "MapboxMaps", run:
cd ios pod update MapboxMaps cd ..
Android: Maven Repository Issues Ensure the Mapbox Maven repository is added after other repositories in your build.gradle.
Expo: Module Not Found Make sure you’ve run npx expo prebuild after adding the plugin to regenerate native code.
Supported Versions
Package Version : 10.3.0-rc.0Mapbox iOS SDK : ~> 11.18.2Mapbox Android SDK : 11.18.2React Native : 0.79+Node.js : 22.16.0 (recommended)
Next Steps
Quickstart Guide Create your first map
Set Access Token Configure your Mapbox token