Installation

This guide will help you install and configure @rnmapbox/maps for iOS, Android, and Expo projects.

Prerequisites

React Native 0.79 or higher
Node.js installed
A Mapbox access token

Step 1: Install the Package

Install @rnmapbox/maps using your preferred package manager:

npm install @rnmapbox/maps

Step 2: Platform-Specific Setup

Choose your platform for detailed setup instructions:

iOS
Android
Expo

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:

cd ios
pod install
cd ..

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>

See Mapbox iOS documentation for more details on location permissions.

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

See the Expo custom native code guide for more information.

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.0
Mapbox iOS SDK: ~> 11.18.2
Mapbox Android SDK: 11.18.2
React Native: 0.79+
Node.js: 22.16.0 (recommended)

Get Started

Guides

Core Concepts

Features

Examples

Installation

Installation

Prerequisites

Step 1: Install the Package

Step 2: Platform-Specific Setup

iOS Configuration

Update Podfile

Install Pods

Add Location Permissions (Optional)

Custom Mapbox Version (Optional)

Android Configuration

Add Mapbox Maven Repository

Custom Mapbox Version (Optional)

Troubleshooting: libc++_shared.so Conflicts

Expo Configuration

Install with Expo CLI

Add Config Plugin

Add Location Permissions (Optional)

Rebuild Your App

Custom Mapbox Version

Step 3: Verify Installation

Troubleshooting

iOS: Pod Install Fails After Upgrade

Android: Maven Repository Issues

Expo: Module Not Found

Supported Versions

Next Steps

Quickstart Guide

Set Access Token

Build docs developers (and LLMs) love

Get Started

Guides

Core Concepts

Features

Examples

​Installation

​Prerequisites

​Step 1: Install the Package

​Step 2: Platform-Specific Setup

​iOS Configuration

​Update Podfile

​Install Pods

​Add Location Permissions (Optional)

​Custom Mapbox Version (Optional)

​Android Configuration

​Add Mapbox Maven Repository

​Custom Mapbox Version (Optional)

​Troubleshooting: libc++_shared.so Conflicts

​Expo Configuration

​Install with Expo CLI

​Add Config Plugin

​Add Location Permissions (Optional)

​Rebuild Your App

​Custom Mapbox Version

​Step 3: Verify Installation

​Troubleshooting

​iOS: Pod Install Fails After Upgrade

​Android: Maven Repository Issues

​Expo: Module Not Found

​Supported Versions

​Next Steps

Quickstart Guide

Set Access Token

Build docs developers (and LLMs) love

Installation

Prerequisites

Step 1: Install the Package

Step 2: Platform-Specific Setup

iOS Configuration

Update Podfile

Install Pods

Add Location Permissions (Optional)

Custom Mapbox Version (Optional)

Android Configuration

Add Mapbox Maven Repository

Custom Mapbox Version (Optional)

Troubleshooting: libc++_shared.so Conflicts

Expo Configuration

Install with Expo CLI

Add Config Plugin

Add Location Permissions (Optional)

Rebuild Your App

Custom Mapbox Version

Step 3: Verify Installation

Troubleshooting

iOS: Pod Install Fails After Upgrade

Android: Maven Repository Issues

Expo: Module Not Found

Supported Versions

Next Steps