This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Maps
A library that provides access to Google Maps on Android and Apple Maps on iOS.
This library is currently in alpha and will frequently experience breaking changes. It is not available in the Expo Go app – use development builds to try it out.
Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
Add Google Maps and Apple Maps to your Expo app with the expo-maps library.
Configuration
Expo Maps provides access to the platform native map APIs on Android and iOS.
- Apple Maps (available on iOSonly). No additional configuration is required to use it after installing this package.
- Google Maps (available on Androidonly). While Google provides a Google Maps SDK for iOS, Expo Maps supports it exclusively on Android. If you want to use Google Maps on iOS, you can look into using an alternative library or writing your own.
Google Cloud API setup
Before you can use Google Maps on Android, you need to register a Google Cloud API project, enable the Maps SDK for Android, and add the associated configuration to your Expo project.
Set up Google Maps on Android
If you have already registered a project for another Google service on Android, such as Google Sign In, you enable the Maps SDK for Android on your project and jump to step 4.
1
Register a Google Cloud API project and enable the Maps SDK for Android
- Open your browser to the Google API Manager and create a project.
- Once it's created, go to the project and enable the Maps SDK for Android.
2
Copy your app's SHA-1 certificate fingerprint
- If you are deploying your app to the Google Play Store, you'll need to upload your app binary to Google Play console at least once. This is required for Google to generate your app signing credentials.
- Go to the Google Play Console > (your app) > Release > Setup > App integrity > App Signing.
- Copy the value of SHA-1 certificate fingerprint.
- If you have already created a development build, your project will be signed using a debug keystore.
- After the build is complete, go to your project's dashboard, then, under Project settings > click Credentials.
- Under Application Identifiers, click your project's package name and under Android Keystore copy the value of SHA-1 Certificate Fingerprint.
3
Create an API key
- Go to Google Cloud Credential manager and click Create Credentials, then API Key.
- In the modal, click Edit API key.
- Under Key restrictions > Application restrictions, choose Android apps.
- Under Restrict usage to your Android apps, click Add an item.
- Add your
android.packagefrom app.json (for example:com.company.myapp) to the package name field. - Then, add the SHA-1 certificate fingerprint's value from step 2.
- Click Done and then click Save.
4
Add the API key to your project
- Copy your API Key into your app.json under the
android.config.googleMaps.apiKeyfield. - Create a new development build, and you can now use the Google Maps API on Android with
expo-maps.
Permissions
To display the user's location on the map, you need to declare and request location permission beforehand. You can configure this using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
Example app.json with config plugin
Configurable properties
Usage
import { AppleMaps, GoogleMaps } from 'expo-maps'; import { Platform, Text } from 'react-native'; export default function App() { if (Platform.OS === 'ios') { return <AppleMaps.View style={{ flex: 1 }} />; } else if (Platform.OS === 'android') { return <GoogleMaps.View style={{ flex: 1 }} />; } else { return <Text>Maps are only available on Android and iOS</Text>; } }
API
import { AppleMaps, GoogleMaps } from 'expo-maps'; // AppleMaps.View and GoogleMaps.View are the React components
Components
Type: React.Element<Component<Omit<AppleMapsViewProps, 'ref'>>>
AppleMapsColorScheme • Default: AppleMapsColorScheme.AUTOMATICControls the color scheme (appearance) of the map. Use this to force the map to display in light or dark mode.
(event: AppleMapsAnnotation) => voidLambda invoked when the annotation is clicked.
(event: CameraMoveEvent) => voidLambda invoked when the map was moved by the user. Also runs once on initial mount with the starting viewport.
(event: AppleMapsCircle) => voidLambda invoked when the circle is clicked.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.
(event: AppleMapsMarker) => voidLambda invoked when the marker is clicked.
(event: AppleMapsPolygon) => voidLambda invoked when the polygon is clicked.
(event: AppleMapsPolyline) => voidLambda invoked when the polyline is clicked.
Ref<AppleMapsViewType>StyleProp<ViewStyle>AppleMapsUISettingsThe MapUiSettings to be used for UI-specific settings on the map.
Type: React.Element<Component<Omit<GoogleMapsViewProps, 'ref'>>>
GoogleMapsContentPaddingThe padding values used to signal that portions of the map around the edges may be obscured. The map will move the Google logo, etc. to avoid overlapping the padding.
GoogleMapsMapOptionsDefines configuration GoogleMapOptions for a GoogleMap
(event: CameraMoveEvent) => voidLambda invoked when the map was moved by the user. Also runs once on initial mount with the starting viewport.
(event: GoogleMapsCircle) => voidLambda invoked when the circle is clicked.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user clicks on the map. It won't be invoked if the user clicks on POI or a marker.
(event: {
coordinates: Coordinates
}) => voidLambda invoked when the user long presses on the map.
(event: GoogleMapsMarker) => voidLambda invoked when the marker is clicked
(event: {
coordinates: Coordinates,
name: string
}) => voidLambda invoked when a POI is clicked.
(event: GoogleMapsPolygon) => voidLambda invoked when the polygon is clicked.
(event: GoogleMapsPolyline) => voidLambda invoked when the polyline is clicked.
Ref<GoogleMapsViewType>StyleProp<ViewStyle>GoogleMapsUISettingsThe MapUiSettings to be used for UI-specific settings on the map.
GoogleMapsUserLocationUser location, overrides default behavior.
Type: React.Element<GoogleStreetViewProps>
StreetViewCameraPositionStyleProp<ViewStyle>Hooks
Check or request permissions to access the location.
This uses both requestPermissionsAsync and getPermissionsAsync to interact with the permissions.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = useLocationPermissions();
Methods
Promise<PermissionResponse>Promise<PermissionResponse>Types
The event payload for the onCameraMove callback on AppleMaps.View and GoogleMaps.View.
Enums
Controls the color scheme (appearance) of the map.
AppleMapsColorScheme.AUTOMATIC ＝ "AUTOMATIC"The map follows the app's color scheme (light/dark mode).
The style of the polyline.
AppleMapsMapStyleElevation.AUTOMATIC ＝ "AUTOMATIC"The default elevation style, that renders a flat, 2D map.
The type of map to display.
AppleMapsMapType.HYBRID ＝ "HYBRID"A satellite image of the area with road and road name layers on top.
The type of map to display.
GoogleMapsMapType.HYBRID ＝ "HYBRID"Satellite imagery with roads and points of interest overlayed.
Permissions
Android
To show the user's location on the map, the expo-maps library requires the following permissions:
ACCESS_COARSE_LOCATION: for approximate device locationACCESS_FINE_LOCATION: for precise device location
iOS
The following usage description keys are used by this library: