Quickstart
This guide will walk you through creating your first map with @rnmapbox/maps. Make sure you’ve completed the installation before proceeding.
Prerequisites
Get a Mapbox Access Token
Set Your Access Token
Before using any Mapbox components, you need to set your access token. Add this to your app’s entry point (e.g., App.tsx or index.js):
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
Replace <YOUR_ACCESS_TOKEN> with your actual Mapbox access token. Never commit tokens to version control.
Create Your First Map
Here’s a complete example that displays a basic map:
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
const App = () => {
return (
<View style={styles.page}>
<View style={styles.container}>
<Mapbox.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
}
});
This creates a simple map view with default settings. The map will be centered on the world view with standard zoom level.
Add Camera Controls
Enhance your map with camera controls to set the initial position:
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
const App = () => {
return (
<View style={styles.page}>
<View style={styles.container}>
<Mapbox.MapView style={styles.map}>
<Mapbox.Camera
zoomLevel={14}
centerCoordinate={[-74.006, 40.7128]}
/>
</Mapbox.MapView>
</View>
</View>
);
};
export default App;
const styles = StyleSheet.create({
page: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
container: {
height: 300,
width: 300,
},
map: {
flex: 1
}
});
The camera is centered on New York City at zoom level 14. Coordinates are in [longitude, latitude] format.
Show User Location
Display the user’s current location on the map:
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
const App = () => {
return (
<View style={styles.page}>
<View style={styles.container}>
<Mapbox.MapView style={styles.map}>
<Mapbox.Camera
followZoomLevel={12}
followUserLocation
/>
<Mapbox.UserLocation />
</Mapbox.MapView>
</View>
</View>
);
};
export default App;
const styles = StyleSheet.create({
page: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
container: {
height: 300,
width: 300,
},
map: {
flex: 1
}
});
Make sure you’ve added location permissions to your Info.plist (iOS) or AndroidManifest.xml (Android). See the installation guide for details. Use Different Map Styles
Mapbox provides several built-in map styles:
import React from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
const App = () => {
return (
<View style={styles.page}>
<View style={styles.container}>
<Mapbox.MapView
style={styles.map}
styleURL={Mapbox.StyleURL.Satellite}
>
<Mapbox.Camera
zoomLevel={14}
centerCoordinate={[-74.006, 40.7128]}
/>
</Mapbox.MapView>
</View>
</View>
);
};
export default App;
const styles = StyleSheet.create({
page: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
container: {
height: 300,
width: 300,
},
map: {
flex: 1
}
});
Available Style URLs
Optional Configuration
Disable Telemetry
By default, Mapbox collects anonymous telemetry data. You can disable this:
import Mapbox from '@rnmapbox/maps';
Mapbox.setTelemetryEnabled(false);
Android Connection Status
If you’re hosting styles on localhost (Android only), you may need to manually set the connection status:
import Mapbox from '@rnmapbox/maps';
Mapbox.setConnected(true);
This bypasses the ConnectivityManager and is only needed for local development with custom styles.
Full Working Example
Here’s a complete, production-ready example with user location and custom styling:
import React, { useEffect } from 'react';
import { StyleSheet, View } from 'react-native';
import Mapbox from '@rnmapbox/maps';
Mapbox.setAccessToken('<YOUR_ACCESS_TOKEN>');
const App = () => {
useEffect(() => {
// Start location manager
Mapbox.locationManager.start();
return () => {
// Cleanup on unmount
Mapbox.locationManager.stop();
};
}, []);
return (
<View style={styles.page}>
<View style={styles.container}>
<Mapbox.MapView
style={styles.map}
styleURL={Mapbox.StyleURL.Street}
>
<Mapbox.Camera
followZoomLevel={12}
followUserLocation
/>
<Mapbox.UserLocation
onPress={() => alert('You pressed the user location!')}
/>
</Mapbox.MapView>
</View>
</View>
);
};
export default App;
const styles = StyleSheet.create({
page: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#F5FCFF'
},
container: {
height: 300,
width: 300,
backgroundColor: 'tomato'
},
map: {
flex: 1
}
});
Next Steps
Now that you have a working map, explore more features:
MapView Component
Learn about all MapView properties and events
Camera Component
Control camera position, zoom, and animations
Add Markers
Display point annotations and markers
Style Layers
Customize map appearance with layers
Common Issues
Map Not Displaying
- Verify your access token is set correctly
- Check that you’ve completed platform-specific setup
- Ensure the map container has a valid height and width
Location Not Showing
- Add location permissions to
Info.plist (iOS) or AndroidManifest.xml (Android)
- Call
Mapbox.locationManager.start() before showing user location
- Test on a physical device (simulators may not have location data)
Build Errors
- Run
pod install after installing (iOS)
- Clean build folder and rebuild
- Check that you’re using React Native 0.79+
Need help?
Join the discussion on GitHub or the Mapbox Discord