React Native Maps

Common errors

• Android app crashes on map interaction or lifecycle events on some devices.

  cause Known issues with Android native module lifecycle (`doDestroy`) or rendering logic.
  fix Upgrade to `react-native-maps@1.26.18` or newer, which includes fixes for crashes related to `doDestroy` and `getFeatureAt`.

• iOS map's bottom inset is incorrect or adjusts unexpectedly during initialization, obscuring UI elements.

  cause Automatic bottom inset adjustment during map view initialization on iOS.
  fix Upgrade to `react-native-maps@1.26.20` or newer, which includes a fix to prevent auto bottom inset adjustment on iOS.

• Markers are not displayed correctly, or they disappear/reappear unexpectedly on Android.

  cause Incorrect native handling of marker addition and removal within the Android map view.
  fix Upgrade to `react-native-maps@1.26.15` or newer, which contains fixes for correctly adding and removing markers on Android.

Warnings

• breaking React Native New Architecture (Fabric) compatibility requires specific `react-native-maps` versions. Upgrading React Native or `react-native-maps` can lead to build failures if versions are not aligned.
  Fix: For `react-native-maps` v1.26.1+, ensure React Native is `>=0.81.1`. For `react-native-maps` v1.26.0 and below, React Native `>=0.76` is required for Fabric. Check the official compatibility table in the documentation.
• gotcha Using custom React Native views inside `<Marker />` components for rendering custom markers can significantly impact performance, especially with many markers.
  Fix: For better performance, consider using the `image` prop with pre-rendered native image assets (PNGs) rather than complex custom views. Only use custom views if absolutely necessary and optimize them carefully.
• gotcha When providing a custom marker image, using `image={require('path/to/image.png')}` might not scale optimally across different screen densities compared to using `image={{ uri: 'image_asset_name' }}` with properly configured native asset bundles.
  Fix: For best scaling, generate multiple resolution `png` images (e.g., `custom_pin.png`, `custom_pin@2x.png`, `custom_pin@3x.png`), place them in Android drawables and iOS asset catalogs, and refer to them by `uri: 'custom_pin'`.
• breaking An unstable Android API `MapUIBlock` caused issues prior to version `1.27.0`, leading to potential crashes or unexpected behavior on Android devices.
  Fix: Upgrade `react-native-maps` to version `1.27.0` or newer to resolve stability issues related to `MapUIBlock` on Android.

Install

• npm install react-native-maps npm
• yarn add react-native-maps yarn
• pnpm add react-native-maps pnpm

Imports

• MapView
  wrong:

  const MapView = require('react-native-maps');

  correct:

  import MapView from 'react-native-maps';

  While CommonJS `require` is supported for backwards compatibility, ESM `import` is the idiomatic and recommended approach for modern React Native projects.
• Marker
  wrong:

  import MapView, { Marker } from 'react-native-maps';

  correct:

  import { Marker } from 'react-native-maps';

  Marker is a named export, not part of the default MapView export. Importing `MapView` and `{ Marker }` separately is common.
• PROVIDER_GOOGLE
  wrong:

  import MapView, { PROVIDER_GOOGLE } from 'react-native-maps';

  correct:

  import { PROVIDER_GOOGLE } from 'react-native-maps';

  Used to explicitly specify the map provider, especially for using Google Maps on iOS or ensuring Google Maps on Android.

Quickstart

This quickstart renders a full-screen map centered on a specific region with a single interactive marker, demonstrating basic setup and controlled region state in a functional React Native component.

import React, { useState } from 'react';
import { StyleSheet, View } from 'react-native';
import MapView, { Marker, type Region } from 'react-native-maps';

export default function App() {
  const [region, setRegion] = useState<Region>({
    latitude: 37.78825,
    longitude: -122.4324,
    latitudeDelta: 0.0922,
    longitudeDelta: 0.0421,
  });

  const handleRegionChangeComplete = (newRegion: Region) => {
    setRegion(newRegion);
  };

  return (
    <View style={styles.container}>
      <MapView
        style={styles.map}
        region={region}
        onRegionChangeComplete={handleRegionChangeComplete}
      >
        <Marker
          coordinate={{ latitude: 37.78825, longitude: -122.4324 }}
          title="My Location"
          description="A sample marker on the map"
        />
      </MapView>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  map: {
    width: '100%',
    height: '100%',
  },
});