Skip to main content

​
Overview

This guide helps you migrate between major versions of @rnmapbox/maps. Each section covers breaking changes and required updates for specific version upgrades.

​
Migrating to v11 (Current)

The library now exclusively supports Mapbox Maps SDK v11 and React Native’s New Architecture (Fabric/TurboModules).

​
Prerequisites

  • React Native 0.79 or higher
  • New Architecture enabled (Fabric/TurboModules)
  • Node.js v22.16.0 or higher

​
Breaking Changes

1

React Native version requirement

Update to React Native 0.79 or higher, which includes the New Architecture by default.
npm install react-native@latest
# or
yarn upgrade react-native@latest
2

Mapbox SDK v11

The library now uses Mapbox Maps SDK v11. Review the Mapbox v11 migration guide for platform-specific changes.Key updates:
  • New style configuration API
  • Slot-based layer positioning
  • Model layers support
  • Updated terrain and 3D features
3

LocationPuck replaces UserLocation renderMode

The UserLocation component’s renderMode prop is deprecated. Use the new LocationPuck component for native user location rendering:Before (v10):
<UserLocation renderMode="native" />
After (v11):
<LocationPuck puckBearingEnabled puckBearing="heading" />
4

Viewport replaces Camera tracking modes

Camera#onUserTrackingModeChange is deprecated. Use Viewport#onStatusChanged instead:Before (v10):
<Camera
  followUserLocation
  followUserMode="normal"
  onUserTrackingModeChange={handleChange}
/>
After (v11):
<Viewport
  onStatusChanged={handleStatusChange}
>
  {/* viewport configuration */}
</Viewport>

​
Migrating to v10 from v8/v9

​
Package Name Change

The package name changed from @react-native-mapbox-gl/maps to @rnmapbox/maps.
1

Update package name

Uninstall the old package and install the new one:
npm uninstall @react-native-mapbox-gl/maps
npm install @rnmapbox/maps
2

Update imports

Update all imports in your code:Before:
import MapboxGL from '@react-native-mapbox-gl/maps';
After:
import Mapbox from '@rnmapbox/maps';
You can use tools like babel-plugin-transform-rename-import to maintain old imports during migration.

​
Setup Changes

Update your Podfile hooks:Before:
pre_install do |installer|
  $RNMBGL.pre_install(installer)
end

post_install do |installer|
  $RNMBGL.post_install(installer)
end
After:
pre_install do |installer|
  $RNMapboxMaps.pre_install(installer)
end

post_install do |installer|
  $RNMapboxMaps.post_install(installer)
end

​
MapLibre Support

Version 10 introduced MapLibre as an option. To use MapLibre: iOS: 
$RNMapboxMapsImpl = 'maplibre'
Android: 
buildscript {
    ext {
        RNMapboxMapsImpl = 'maplibre'
    }
}
When using MapLibre, you must set the tile server: 
import Mapbox from '@rnmapbox/maps';

Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
Mapbox.setWellKnownTileServer('Mapbox'); // or 'MapLibre'

​
Migrating to v8 from v7

​
StyleSheet Changes

StyleSheet.create and StyleSheet.identity were removed in favor of expressions: Before (v7): 
const styles = MapboxGL.StyleSheet.create({
  fillLayer: {
    fillColor: MapboxGL.StyleSheet.identity('color'),
  },
});
After (v8): 
const styles = {
  fillLayer: {
    fillColor: ['get', 'color'],
  },
};

​
Camera Component

Camera-related properties moved from MapView to the Camera component: Before (v7): 
<MapView
  zoomLevel={8}
  centerCoordinate={[-111.8678, 40.2866]}
  userTrackingMode={UserTrackingModes.Follow}
>
  {/* content */}
</MapView>
After (v8): 
<MapView>
  <Camera
    zoomLevel={8}
    centerCoordinate={[-111.8678, 40.2866]}
    followUserLocation
    followUserMode="normal"
  />
  {/* content */}
</MapView>

​
User Tracking Mode

  • MapView#userTrackingMode → Camera#followUserMode and Camera#followUserLocation
  • followUserMode uses strings: 'normal', 'compass', 'course'
  • UserTrackingModes enum is deprecated

​
ShapeSource Images

ShapeSource#images was deprecated. Use the Images component: Before (v7): 
<ShapeSource images={{ pin, dot }} />
After (v8): 
<Images images={{ pin, dot }} />
<ShapeSource>
  <SymbolLayer />
</ShapeSource>

​
Event Payload Changes

VectorSource and SymbolSource onPress events changed: Before (v7): 
onPress={(event) => {
  const feature = event.nativeEvent.payload;
}}
After (v8): 
onPress={(event) => {
  const { features, point, coordinates } = event.nativeEvent.payload;
}}

​
Removed APIs

  • isTelemetryEnabled removed (Android compatibility)
  • geoUtils made private - use Turf.js instead
  • MapView#flyTo, MapView#fitBounds, MapView#moveTo, MapView#zoomTo moved to Camera

​
General Migration Tips

1

Review release notes

Check the GitHub releases page for detailed release notes and additional changes.
2

Update native dependencies

After upgrading, always update native dependencies:iOS:
cd ios && pod install
Android:
cd android && ./gradlew clean
3

Test thoroughly

Test all map-related features in your app:
  • Map rendering and styles
  • User location and tracking
  • Annotations and markers
  • Camera movements
  • Custom sources and layers
4

Check for deprecation warnings

Run your app in development mode and check the console for deprecation warnings. Address these before they become breaking changes in future versions.

​
Getting Help

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us