{"id":11782,"library":"react-native-maps","title":"React Native Maps","description":"React Native Maps is a comprehensive, community-maintained library providing native map components for both iOS and Android platforms, allowing developers to integrate highly customizable maps into their React Native applications. It supports popular map services like Apple Maps (MapKit) on iOS and Google Maps on Android, with an optional Google Maps provider for iOS as well. The current stable version is `1.27.2`, and the project demonstrates an active development cadence with multiple bug fix and minor releases occurring monthly or bi-monthly, reflecting continuous maintenance and improvement. Its key differentiator lies in its declarative, React-like API, enabling map features such as Markers, Polylines, Polygons, Circles, Overlays, and Heatmaps to be defined as children of the `<MapView />` component. This approach simplifies map state management and interaction. The library also emphasizes compatibility with both the \"Old Architecture\" and the newer \"Fabric (New Architecture)\" of React Native, though specific version requirements apply to each, which are crucial considerations for developers.","status":"active","version":"1.27.2","language":"javascript","source_language":"en","source_url":"https://github.com/react-native-maps/react-native-maps","tags":["javascript","react","react-native","react-component","map","mapview","google-maps","mapkit","typescript"],"install":[{"cmd":"npm install react-native-maps","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-maps","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-maps","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native applications.","package":"react","optional":false},{"reason":"Core dependency for all React Native applications.","package":"react-native","optional":false},{"reason":"Peer dependency, potentially used for web compatibility but primarily a native module.","package":"react-native-web","optional":true}],"imports":[{"note":"While CommonJS `require` is supported for backwards compatibility, ESM `import` is the idiomatic and recommended approach for modern React Native projects.","wrong":"const MapView = require('react-native-maps');","symbol":"MapView","correct":"import MapView from 'react-native-maps';"},{"note":"Marker is a named export, not part of the default MapView export. Importing `MapView` and `{ Marker }` separately is common.","wrong":"import MapView, { Marker } from 'react-native-maps';","symbol":"Marker","correct":"import { Marker } from 'react-native-maps';"},{"note":"Used to explicitly specify the map provider, especially for using Google Maps on iOS or ensuring Google Maps on Android.","wrong":"import MapView, { PROVIDER_GOOGLE } from 'react-native-maps';","symbol":"PROVIDER_GOOGLE","correct":"import { PROVIDER_GOOGLE } from 'react-native-maps';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { StyleSheet, View } from 'react-native';\nimport MapView, { Marker, type Region } from 'react-native-maps';\n\nexport default function App() {\n  const [region, setRegion] = useState<Region>({\n    latitude: 37.78825,\n    longitude: -122.4324,\n    latitudeDelta: 0.0922,\n    longitudeDelta: 0.0421,\n  });\n\n  const handleRegionChangeComplete = (newRegion: Region) => {\n    setRegion(newRegion);\n  };\n\n  return (\n    <View style={styles.container}>\n      <MapView\n        style={styles.map}\n        region={region}\n        onRegionChangeComplete={handleRegionChangeComplete}\n      >\n        <Marker\n          coordinate={{ latitude: 37.78825, longitude: -122.4324 }}\n          title=\"My Location\"\n          description=\"A sample marker on the map\"\n        />\n      </MapView>\n    </View>\n  );\n}\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n  },\n  map: {\n    width: '100%',\n    height: '100%',\n  },\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.26.0"},{"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.","message":"Using custom React Native views inside `<Marker />` components for rendering custom markers can significantly impact performance, especially with many markers.","severity":"gotcha","affected_versions":"All"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade `react-native-maps` to version `1.27.0` or newer to resolve stability issues related to `MapUIBlock` on Android.","message":"An unstable Android API `MapUIBlock` caused issues prior to version `1.27.0`, leading to potential crashes or unexpected behavior on Android devices.","severity":"breaking","affected_versions":"<1.27.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade to `react-native-maps@1.26.18` or newer, which includes fixes for crashes related to `doDestroy` and `getFeatureAt`.","cause":"Known issues with Android native module lifecycle (`doDestroy`) or rendering logic.","error":"Android app crashes on map interaction or lifecycle events on some devices."},{"fix":"Upgrade to `react-native-maps@1.26.20` or newer, which includes a fix to prevent auto bottom inset adjustment on iOS.","cause":"Automatic bottom inset adjustment during map view initialization on iOS.","error":"iOS map's bottom inset is incorrect or adjusts unexpectedly during initialization, obscuring UI elements."},{"fix":"Upgrade to `react-native-maps@1.26.15` or newer, which contains fixes for correctly adding and removing markers on Android.","cause":"Incorrect native handling of marker addition and removal within the Android map view.","error":"Markers are not displayed correctly, or they disappear/reappear unexpectedly on Android."}],"ecosystem":"npm"}