Adding Native Maps to a React Native App
Set up expo-maps in React Native with native Apple and Google maps, shared markers, location permissions, camera controls, Android API keys, and iOS version limits.
Install expo-maps in a development build, then render AppleMaps.View on iOS and GoogleMaps.View on Android. Both components take the same camera, marker and location data, so one wrapper covers both platforms.
Most map tutorials for React Native are written for react-native-maps, so their props don’t carry over to Expo’s library. Copy a <MapView> snippet into an expo-maps project and you get type errors on everything, including the camera.
This guide covers the whole flow in expo-maps: picking the library, building the app, adding the Android API key, rendering a map on both platforms, adding markers, centring on the user and handling marker taps. It also covers the iOS version limits that decide which features you can use. If you want vector tiles and custom styles from Mapbox instead, see creating a React Native map with Mapbox.
Key Takeaways
- expo-maps shows Apple Maps on iOS and Google Maps on Android through two components,
AppleMaps.ViewandGoogleMaps.View, and it does not support Google Maps on iOS. - Run expo-maps in a development build. Apple Maps needs no API key, but Android needs a Google Maps key at
android.config.googleMaps.apiKeyin app.json, followed by a rebuild. cameraPositiononly sets where the map starts. To move the camera later, callsetCameraPositionon a ref to the map.- Expo’s docs list iOS 17 as the minimum for expo-maps, and marker tap callbacks such as
onMarkerClickneed iOS 18.
Should You Use expo-maps or react-native-maps?
For an Expo project that already uses development builds, choose expo-maps. Choose react-native-maps if you need Google Maps on iOS or need to run inside Expo Go. expo-maps is Expo’s own maps library, and it renders through SwiftUI on iOS and Jetpack Compose on Android. react-native-maps is community-maintained and gives you one MapView API that works with several map providers.
| expo-maps | react-native-maps | |
|---|---|---|
| Built by | Expo team | Community |
| Native layer | SwiftUI (iOS), Jetpack Compose (Android) | One MapView component |
| iOS provider | Apple Maps only | Apple Maps or Google Maps |
| iOS minimum | iOS 17 per Expo’s docs; the package README states iOS 18.0 | Not covered here |
| Expo Go | Use a development build | Included in Expo Go, per Expo’s docs |
| React components as markers | Not supported (image markers instead) | Supported |
| API shape | Two platform components | One component |
At launch, the expo-maps announcement described the library as an alpha: “With SDK 53, we are releasing our alpha version of expo-maps.” The SDK 58 reference page shows no status label. Check the expo-maps reference for the current status before you ship. Expo’s react-native-maps page covers the other option.
Install expo-maps and Create a Development Build
expo-maps needs two things: the package and a native binary (a development build) that includes it. Install the package with the Expo CLI so the version matches your SDK:
npx expo install expo-maps expo-location expo-dev-client
npx expo run:ios # or: npx expo run:android
expo-location supplies the user’s coordinates later in this guide. expo-dev-client turns the binary into a development build. The expo-maps docs only describe running it in a development build, so use one. You can also build in the cloud with EAS. For a ready-made project, npx create-expo-app --example with-maps starts with expo-maps already installed and configured.
Add the Android Google Maps API Key
Apple Maps works without a key. Google Maps on Android needs a Google Cloud API key with the Maps SDK for Android enabled, added to app.json, and then a rebuild of the app.
- Create a Google Cloud project and enable Maps SDK for Android.
- Create an API key and restrict it to Android apps using your package name and the SHA-1 fingerprint of your signing certificate. For EAS builds,
eas credentialsshows the fingerprint. - Add the key and the location permission plugin to app.json:
{
"expo": {
"android": {
"package": "com.example.places",
"config": {
"googleMaps": { "apiKey": "YOUR_ANDROID_MAPS_KEY" }
}
},
"plugins": [
[
"expo-maps",
{
"requestLocationPermission": true,
"locationPermission": "Allow $(PRODUCT_NAME) to show your position on the map"
}
]
]
}
}
- Rebuild with
npx expo run:android. A JavaScript reload does not pick up changes to native config.
In the plugin options, requestLocationPermission is a boolean that adds permissions to AndroidManifest.xml and Info.plist, and locationPermission sets the iOS-only usage message. app.json can’t read environment variables. To keep the key out of source control, move the same android.config.googleMaps.apiKey path into app.config.js and read the key from process.env there.
Show a Map on Both Platforms
expo-maps has no cross-platform component, so write a small wrapper that chooses AppleMaps.View or GoogleMaps.View based on Platform.OS and passes both the same cameraPosition. A CameraPosition is an object with coordinates and zoom:
import { Platform, Text } from 'react-native';
import { AppleMaps, GoogleMaps } from 'expo-maps';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
export function BasicMap() {
if (Platform.OS === 'ios') return <AppleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
if (Platform.OS === 'android') return <GoogleMaps.View style={{ flex: 1 }} cameraPosition={START} />;
return <Text>Maps are only available on Android and iOS.</Text>;
}
The final branch handles web and any other platform, where neither component exists.
Add Markers from One Data Array
Both AppleMaps.View and GoogleMaps.View take a markers array, and both marker types accept id, title and coordinates. That means one mapping function can feed both platforms. Add platform-only fields, such as tintColor on Apple or snippet on Google, by spreading them onto the shared marker:
type Place = { id: string; title: string; latitude: number; longitude: number };
export const PLACES: Place[] = [
{ id: 'office', title: 'Office', latitude: 51.5154, longitude: -0.141 },
{ id: 'cafe', title: 'Cafe', latitude: 51.5113, longitude: -0.1198 },
];
export const toMarker = (p: Place) => ({
id: p.id,
title: p.title,
coordinates: { latitude: p.latitude, longitude: p.longitude },
});
// iOS: markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
// Android: markers={PLACES.map((p) => ({ ...toMarker(p), snippet: 'Open now' }))}
expo-maps can’t render React components as markers. For custom pins, it supports image icons loaded with useImage from expo-image.
How Do You Show and Centre on the User’s Location?
Showing the user’s location in expo-maps takes three steps: request location permission, show the location dot once permission is granted, and move the camera when the coordinates arrive. The permission has to be both declared in the build and requested at runtime before the dot can appear. The useLocationPermissions hook from expo-maps returns the current status and a function to request it.
| Task | AppleMaps.View | GoogleMaps.View |
|---|---|---|
| Location dot | properties.isMyLocationEnabled | properties.isMyLocationEnabled plus userLocation |
| Follow the user | Call setCameraPosition | userLocation.followUserLocation |
| Animation duration | Not supported | duration in ms |
Only enable the dot after permission is granted. A reported Android issue showed that turning isMyLocationEnabled on without the permission crashed the app on Android, while iOS ignored it. A fix was merged into Expo’s main branch on 4 November 2026, but older expo-maps releases don’t have it, and gating the dot on permission works on every version. The issue also points out that the config plugin’s requestLocationPermission option only declares the permissions at build time and never requests anything at runtime.
In expo-maps, the cameraPosition prop is documented as the initial camera position of the map, so changing it in state isn’t the documented way to move the camera. Call setCameraPosition on a ref instead. On iOS, animation duration is not supported, and the returned promise resolves after the camera update is scheduled, not when its animation finishes.
import { useEffect, useRef, useState, type ComponentRef } from 'react';
import { Platform, Text, View } from 'react-native';
import { AppleMaps, GoogleMaps, useLocationPermissions } from 'expo-maps';
import * as Location from 'expo-location';
import { PLACES, toMarker } from './places';
const START = { coordinates: { latitude: 51.5074, longitude: -0.1278 }, zoom: 12 };
type Coords = { latitude: number; longitude: number };
export function PlacesMap({ onSelect }: { onSelect: (id: string) => void }) {
const appleRef = useRef<ComponentRef<typeof AppleMaps.View>>(null);
const [permission, requestPermission] = useLocationPermissions();
const [me, setMe] = useState<Coords | null>(null);
const granted = !!permission?.granted;
useEffect(() => {
if (permission && !permission.granted && permission.canAskAgain) requestPermission();
}, [permission]);
useEffect(() => {
if (!granted) return;
Location.getCurrentPositionAsync().then(({ coords }) => {
const here = { latitude: coords.latitude, longitude: coords.longitude };
setMe(here);
appleRef.current?.setCameraPosition({ coordinates: here, zoom: 14 }); // iOS only; no duration
});
}, [granted]);
const handleMarker = (m: { id?: string }) => m.id && onSelect(m.id);
const denied = permission && !permission.granted && !permission.canAskAgain;
const map =
Platform.OS === 'ios' ? (
<AppleMaps.View
ref={appleRef}
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map((p) => ({ ...toMarker(p), tintColor: '#e5484d' }))}
properties={{ isMyLocationEnabled: granted }}
onMarkerClick={handleMarker} // iOS 18+
/>
) : Platform.OS === 'android' ? (
<GoogleMaps.View
style={{ flex: 1 }}
cameraPosition={START}
markers={PLACES.map(toMarker)}
properties={{ isMyLocationEnabled: granted }}
userLocation={me ? { coordinates: me, followUserLocation: true } : undefined}
onMarkerClick={handleMarker}
/>
) : (
<Text>Maps are only available on Android and iOS.</Text>
);
return (
<View style={{ flex: 1 }}>
{map}
{denied && <Text>Location is off. Enable it in Settings to see where you are.</Text>}
</View>
);
}
Location.getCurrentPositionAsync supplies the coordinates. On Android, followUserLocation keeps the camera on the user, so the code only calls setCameraPosition on iOS. If permission is denied for good, the map stays at START and a non-blocking message appears below it.
Respond to Marker Taps with onMarkerClick
To handle marker taps in expo-maps, pass onMarkerClick to AppleMaps.View or GoogleMaps.View. The callback receives the tapped marker, so you can read its id and find the matching record in your data. On Android it works on every supported version. On iOS, Expo’s docs mark it iOS 18.0+, and the same limit applies to the other tap callbacks and to programmatic selection with selectMarker and selectAnnotation.
On iOS 17 devices the map still renders, but tapping a marker does nothing in JavaScript. If tap-driven UI is required, set ios.deploymentTarget to 18.0 via expo-build-properties. Otherwise, add a list below the map that drives the same selection state, so iOS 17 users can still reach each place.
Conclusion
expo-maps covers the common map screen with native components: Apple Maps on iOS, Google Maps on Android, one shared data array and a short Platform.OS branch. Next, rebuild with your Android key and test on a real iOS 17 device and an iOS 18 device. That is where the tap and permission differences show up. After release, session replay for React Native shows the failures you can’t see in logs, such as users panning around looking for a pin or dismissing the location prompt. Watching those sessions tells you whether the map flow works for real users.
FAQs
Why does the Google map work in development but stay blank in the Play Store build?
The API key is usually restricted to the wrong SHA-1 fingerprint. With Play App Signing, Google re-signs the release, so the installed app carries Google's app signing certificate instead of your upload or debug key. Copy the app signing SHA-1 from the App integrity page in Play Console and add it to the key's Android app restrictions. Keep your development fingerprint on the key as well.
Can expo-maps draw routes, areas or radius circles?
Yes. Both AppleMaps.View and GoogleMaps.View accept polylines, polygons and circles props. Each prop takes an array of shapes built from coordinates, and a circle takes a center and a radius in metres. expo-maps draws shapes but does not calculate routes. For a driving or walking path, get the route geometry from a directions service and pass the decoded coordinates as a polyline.
How do I switch expo-maps to a satellite view?
Set mapType inside the properties prop. On AppleMaps.View, use the AppleMapsMapType enum: STANDARD, IMAGERY (satellite only) or HYBRID (satellite with roads and labels). On GoogleMaps.View, use GoogleMapsMapType: NORMAL, SATELLITE, HYBRID or TERRAIN. The value names differ by platform, so a shared wrapper should map one setting, such as 'satellite', to IMAGERY on iOS and SATELLITE on Android.
Does location permission granted through expo-maps also cover expo-location?
Yes. Android and iOS grant location access to the app as a whole, not to a single library. Once the user accepts the foreground prompt from the useLocationPermissions hook in expo-maps, expo-location sees the same permission, so getCurrentPositionAsync runs without a second prompt. Background location is a separate grant on both platforms and needs its own request through expo-location.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k