Mapbox in React Native means one package in 2026: @rnmapbox/maps. It is community maintained, it wraps the Mapbox Maps SDK v11 for iOS and Android, and it is the thing you reach for when the default map stops being enough: custom styles that match your brand, 3D terrain, thousands of points that still scroll smoothly, offline regions. This guide walks through a working setup with current versions, the five components you will use on day one, and the mistakes that cost us time.
Everything here was checked against @rnmapbox/maps 10.3.18 (released November 11, 2026), which needs React Native 0.79 or later and Mapbox Maps SDK 11.33.0 or newer.
Mapbox or react-native-maps?
Decide this first, because switching later is a rewrite of every map screen.
| Library | Version (Nov 2026) | npm downloads / week | What it renders | Pick it when |
|---|---|---|---|---|
react-native-maps |
1.29.11 | about 1.7M | Apple Maps on iOS, Google Maps on Android | You need a pin on a map and platform-native look |
@rnmapbox/maps |
10.3.18 | about 349K | Mapbox vector maps on both platforms | Custom styling, data layers, 3D, offline, identical look across platforms |
@maplibre/maplibre-react-native |
11.5.1 | about 397K | MapLibre Native, any tile source | You want the same layer model without a Mapbox account |
expo-maps |
58.0.11 | about 252K | Apple Maps / Google Maps via Expo UI | Simple maps in an Expo app |
My rule of thumb: if the map is a feature (a store locator, a delivery address), use react-native-maps. If the map is the product (fleet tracking, outdoor routes, real estate search), use Mapbox or MapLibre. Note that MapLibre now has slightly more weekly downloads than the Mapbox wrapper. It started as a fork of Mapbox GL before the license change, the component model is close, and it is worth a look if usage-based pricing worries you.
On pricing: Mapbox bills mobile SDKs by monthly active users with a free allowance. The numbers change, so read the pricing page before you commit, and do the arithmetic for your expected MAU, not your current one.
Install @rnmapbox/maps
You need a Mapbox account and a public access token (it starts with pk.). One thing has become simpler: Mapbox lifted the authentication requirement on SDK downloads, so the secret MAPBOX_DOWNLOADS_TOKEN that every older tutorial tells you to put in .netrc and gradle.properties is no longer needed. If your project still has one, you can delete it.
Expo (the easy path)
The library has native code, so it does not run in Expo Go. You need a development build.
npx expo install @rnmapbox/maps expo-location
Then add both config plugins to app.json:
{
"expo": {
"plugins": [
["@rnmapbox/maps", { "RNMapboxMapsVersion": "11.33.0" }],
[
"expo-location",
{ "locationWhenInUsePermission": "Show current location on map." }
]
]
}
}
npx expo prebuild --clean
npx expo run:ios # or run:android
RNMapboxMapsVersion is optional. Pin it only if you have a reason, and revisit it every time you upgrade the JS package. Setting an older native SDK than the wrapper expects is the most common build failure in the issue tracker.
Bare React Native
npm install @rnmapbox/maps
iOS: add the hooks to your ios/Podfile and run pod install.
pre_install do |installer|
$RNMapboxMaps.pre_install(installer)
end
post_install do |installer|
$RNMapboxMaps.post_install(installer)
# ...your existing react_native_post_install call stays here
end
Add NSLocationWhenInUseUsageDescription to Info.plist if you show the user’s location. There is also an experimental Swift Package Manager path ($RNMapboxMapsSwiftPackageManager = true at the top of the Podfile), useful if another package such as the Navigation SDK already brings the Maps SDK.
Android: add the Mapbox Maven repository in android/build.gradle.
allprojects {
repositories {
maven { url 'https://api.mapbox.com/downloads/v2/releases/maven' }
}
}
Your first map
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox, { MapView, Camera } from '@rnmapbox/maps';
Mapbox.setAccessToken(process.env.EXPO_PUBLIC_MAPBOX_TOKEN!);
export default function MapScreen() {
return (
<View style={styles.page}>
<MapView style={styles.map} styleURL="mapbox://styles/mapbox/standard">
<Camera
defaultSettings={{
centerCoordinate: [-0.1276, 51.5072], // [longitude, latitude]
zoomLevel: 11,
}}
/>
</MapView>
</View>
);
}
const styles = StyleSheet.create({
page: { flex: 1 },
map: { flex: 1 },
});
Two things to burn into memory.
Coordinates are [longitude, latitude]. GeoJSON order, the opposite of Google Maps and of how people say it out loud. If your map opens in the ocean off the coast of Somalia or in Antarctica, you swapped them. Everyone does it once.
The map needs a size. A MapView inside a parent without flex: 1 or explicit dimensions renders as nothing, with no error. Blank map, no warning: check the layout before the token.
Moving the camera
Camera is a child of MapView, and it works in two modes. defaultSettings sets the starting position once. Props such as centerCoordinate and zoomLevel are declarative: change them and the camera animates. For imperative moves, use a ref.
const camera = useRef<Camera>(null);
// fly to a point over two seconds
camera.current?.setCamera({
centerCoordinate: [2.3522, 48.8566],
zoomLevel: 13,
animationMode: 'flyTo',
animationDuration: 2000,
});
// fit two corners with padding
camera.current?.fitBounds([2.41, 48.9], [2.25, 48.81], [40, 40], 1000);
animationMode accepts flyTo, easeTo, linearTo, moveTo and none. To follow the user, set followUserLocation and followZoomLevel on the camera and stop there. Do not also feed it coordinates from your own location listener, or the two will fight.
Markers: three options, pick by count
This is the section most tutorials get wrong, and it is where map performance is won or lost.
MarkerViewrenders real React Native views on the map. Fully interactive, any component works inside it, includingPressable. The docs suggest a maximum of around 100 on screen at once.PointAnnotationrenders its children to a bitmap. Fine for a few static pins, but animations inside it freeze at whatever frame the snapshot caught.ShapeSource+SymbolLayerorCircleLayerdraws on the GPU from GeoJSON. This is the answer for hundreds or tens of thousands of points.
import { MarkerView } from '@rnmapbox/maps';
<MarkerView coordinate={[-0.1276, 51.5072]}>
<Pressable onPress={() => openDetails(place)} style={styles.pin}>
<Text style={styles.pinText}>{place.price}</Text>
</Pressable>
</MarkerView>
MarkerView has no onPress of its own. Handle touches in the child views.
Clustering thousands of points
With a ShapeSource you get clustering by setting one prop. The source groups nearby points, and you style clusters and single points as separate layers with a filter.
import { ShapeSource, CircleLayer, SymbolLayer } from '@rnmapbox/maps';
const source = useRef<ShapeSource>(null);
<ShapeSource
id="places"
ref={source}
shape={featureCollection} // GeoJSON FeatureCollection of Points
cluster
clusterRadius={50}
clusterMaxZoomLevel={14}
onPress={async (e) => {
const feature = e.features[0];
if (feature.properties?.cluster) {
const zoom = await source.current?.getClusterExpansionZoom(feature);
camera.current?.setCamera({
centerCoordinate: feature.geometry.coordinates,
zoomLevel: zoom,
animationDuration: 500,
});
} else {
openDetails(feature.properties);
}
}}
>
<CircleLayer
id="clusters"
filter={['has', 'point_count']}
style={{
circleColor: '#2563eb',
circleRadius: ['step', ['get', 'point_count'], 16, 50, 22, 500, 30],
}}
/>
<SymbolLayer
id="cluster-count"
filter={['has', 'point_count']}
style={{ textField: ['get', 'point_count_abbreviated'], textColor: '#fff', textSize: 12 }}
/>
<CircleLayer
id="points"
filter={['!', ['has', 'point_count']]}
style={{ circleColor: '#f97316', circleRadius: 6 }}
/>
</ShapeSource>
Those bracketed arrays are Mapbox style expressions. They look odd for a day and then become the best part of the library: color, size and visibility driven by your data, evaluated natively, with no re-render in JavaScript. Version 10.3.18 also applies ShapeSource data once and off the main thread on Android, which helps when you replace a large collection.
Showing the user’s location
import { LocationPuck } from '@rnmapbox/maps';
<MapView style={{ flex: 1 }}>
<Camera followUserLocation followZoomLevel={15} />
<LocationPuck puckBearing="heading" puckBearingEnabled pulsing={{ isEnabled: true }} />
</MapView>
LocationPuck is the native puck and the cheapest way to show a blue dot. Ask for permission before rendering it: expo-location‘s requestForegroundPermissionsAsync() in Expo, or Mapbox.requestAndroidLocationPermissions() on bare Android. Older posts use androidRenderMode and iosShowsUserHeadingIndicator. Both are deprecated in favour of puckBearing and puckBearingEnabled.
Offline maps
Offline is the feature that most often decides for Mapbox. You download a pack for a bounding box and a zoom range, and the map works without a connection inside it.
await Mapbox.offlineManager.createPack(
{
name: 'london-centre',
styleURL: 'mapbox://styles/mapbox/standard',
minZoom: 10,
maxZoom: 15,
bounds: [[-0.05, 51.55], [-0.2, 51.47]], // [northeast, southwest]
},
(pack, status) => console.log(status.percentage),
(pack, error) => console.warn(error),
);
Be modest with maxZoom. Each extra zoom level roughly quadruples the tile count, and a city at zoom 18 is a download nobody will wait for. There is a tile count limit as well (setTileCountLimit), so test with real regions before you promise offline to a customer.
Problems you will hit
- Blank map, no error. In order of likelihood: the view has no size, the token is missing or was set after the first render, or the style URL is wrong. Call
Mapbox.setAccessTokenat module scope, not in an effect. could not find compatible versions for pod "MapboxMaps"after an upgrade. Your pinned$RNMapboxMapsVersionis older than the wrapper needs. Remove the pin or raise it, thenpod update MapboxMaps.- Android:
2 files found with path 'lib/arm64-v8a/libc++_shared.so'. AddpickFirstentries forlibc++_shared.sounderpackagingOptionsinandroid/app/build.gradle. The install doc has the exact block. - Works in dev, crashes in Expo Go. Expected. Use a development build.
- Janky pan with many markers. You are using
MarkerViewfor a job that belongs to a layer. Move toShapeSource. - Telemetry. Mapbox collects anonymous usage data by default. If your privacy policy or your sector needs it off, call
Mapbox.setTelemetryEnabled(false)and say so in your security review.
FAQ
Is @rnmapbox/maps the official Mapbox SDK for React Native?
No. It is a community-supported open-source library that wraps the official native SDKs. Mapbox does not publish a first-party React Native package. The maintainers have an open call for additional maintainers, though releases are frequent: six in the three weeks before this post.
Does Mapbox work with Expo?
Yes, through the config plugin and a development build or EAS Build. It does not work in Expo Go because it needs custom native code.
Do I still need a secret download token?
No. The install docs state that Mapbox lifted the auth requirement from SDK downloads. You only need the public access token at runtime.
Does it support the New Architecture?
Yes. The package requires React Native 0.79 or later, and since 0.82 the New Architecture is the only one there is. If that sentence is news, our explainer on how React Native works has the background.
Can I get turn-by-turn navigation?
There is a separate package, @rnmapbox/navigation (0.1.2), which dropped its alpha label in November 2026. It is young and has few users so far. Budget time for testing before you rely on it.
Start with the smallest thing: one map, one camera, one layer of your own data. Mapbox rewards teams that learn sources, layers and expressions early, and punishes those who try to build everything out of marker components.