react-native-maps: declarative map children, strict React Native version gates, and offline tiles that are not offline
React Native Mapview component for iOS + Android
At a glance
- What is it?
- react-native-maps is the MIT-licensed MapView component for iOS and Android in React Native. Its child-component API is easy to read, but the version you can install is tied to your React Native release and architecture, and several features carry platform caveats worth knowing before you build on them.
- Who is it for?
- react-native-maps is the sensible default for a React Native app that needs markers, polygons, callouts and tile overlays on iOS and Android, written as ordinary JSX children. It is the wrong choice if you cannot move to React Native 0.81.1 on the New Architecture and need current releases, or if you need truly offline maps on Android without extra configuration.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- react-native-maps/react-native-maps16,017 ★ · +18
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| react-native-maps/react-native-maps | 16k | 16k |
18 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Map features are children of MapView
The central design choice is that markers, polygons, polylines, circles, overlays, heatmaps and GeoJSON layers are all declared as children of the MapView itself. You describe what should be on the map, and the component keeps the native map in sync. A map that opens on a fixed region needs only one prop:
<MapView
initialRegion={{
latitude: 37.78825,
longitude: -122.4324,
latitudeDelta: 0.0922,
longitudeDelta: 0.0421,
}}
/>The distinction between initialRegion and region matters. initialRegion only sets where the map starts. If you pass region instead, you are controlling the viewport as state, and the pattern is to update that state from onRegionChange with this.setState({ region }). A list of markers is a plain map() over your data rendering Marker children with coordinate, title and description props, and a Callout nested inside a Marker replaces the default popup with your own view. Each of these components has its own API page under docs/, from mapview.md and marker.md through heatmap.md and geojson.md.
The React Native version decides which release you can install
Compatibility is split by architecture, and the gates are strict. On Fabric, the New Architecture, versions 1.26.1 and later require React Native 0.81.1 or newer, while 1.26.0 and below require React Native 0.76 or newer. On the old architecture, versions 1.14.0 through 1.20.1 require React Native 0.74 or newer, and anything below 1.14.0 works back to React Native 0.64.3.
The package.json for 1.29.11 backs this up with peer dependencies of react 18.3.1 or newer and react-native 0.76.0 or newer, with react-native-web 0.11 or newer as an optional peer.
The consequence for an existing app is that upgrading the map library can force a React Native upgrade. A project on React Native 0.80 cannot take any 1.26.1 or later release, so bug fixes in the 1.29 line are out of reach until the app itself moves. The old architecture table stops at 1.20.1, so an app that has not migrated to Fabric should plan around that version rather than expect newer releases to cover it.
Custom marker views cost performance, required images do not scale
Markers can look three ways, and each has a cost. The cheapest is a native image asset. You generate a png at several resolutions, put the files in the Android drawables and iOS assets directories, and reference it by name:
<Marker
coordinate={{latitude: latitude, longitude: longitude}}
image={{uri: 'custom_pin'}}
/>Passing image binary data with require is possible, but it will not scale well across screen sizes, so stick to native assets if your users span many screen densities. The third option renders an arbitrary React view as the marker by nesting a component inside Marker. That is the most flexible, and it carries performance implications; the project's own advice is to use a custom image instead if you can, and save yourself the headache. On a map with many markers, choose image assets from the start rather than refactoring later. Markers also accept draggable with an onDragEnd handler that hands back the new coordinate in e.nativeEvent.coordinate.
LocalTile does not stop Android from downloading map tiles
For offline use, LocalTile renders tiles stored on the device in the xyz tiling scheme, using a path template such as /storage/emulated/0/mytiles/{z}/{x}/{y}.png and a tileSize, with 256 or 512 as the usual values. The trap is on Android: LocalTile is still just an overlay over the original map tiles. If the device is online, the underlying tiles are still downloaded. To suppress them you have to turn the base map off:
<MapView
mapType={Platform.OS == "android" ? "none" : "standard"}
>If you skip this, an app sold as offline-capable still uses network data on Android whenever a connection exists, and your local tiles sit on top of the downloaded ones. Getting the tiles onto the device is your problem; the project points to the OpenStreetMap wiki for how to download them.
The network-backed variant, UrlTile, takes a urlTemplate with {x}, {y} and {z} placeholders. Its maximumZ setting corresponds to MKTileOverlay and is iOS only. Android apps need the internet permission in AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />On iOS you configure App Transport Security instead.
Overlays sit beside the map, and styling is Google-only
Not everything belongs inside MapView. Buttons, search bars and legends that float over the map go after the MapView closing tag as siblings, absolutely positioned, for example with position absolute and a bottom offset.
Map styling has a platform condition. Customizing the map style is a Google Maps only feature, set through MapView with provider="google" and a googleMapId that points at your styled map. If your iOS build uses the default provider, the style you designed will not appear there, so plan for that difference in design reviews. The package keywords list both google-maps and mapkit, reflecting the two native backends it targets.
A small maintainer group and automated release bursts
The project says plainly that it is maintained by a small group of people and asks for help with issues and pull requests, with guidelines in CONTRIBUTING.md. Releases are automated through semantic-release, which explains the bursts: v1.29.9, v1.29.10 and v1.29.11 were all published on 2026-09-27, within a couple of hours of each other. The last push to master was on 2026-10-19.
For teams depending on it, the practical reading is that fixes arrive, but triage capacity is limited, so a niche bug may wait unless someone contributes a patch. The repository makes contributing approachable: yarn bootstrap installs the example app and its iOS pods, there are Jest tests under __tests__/, Detox end-to-end tests under e2e/, and a full example/ app with its own Android and iOS projects. The published package ships src, dist, the android and ios native code, the podspec, app.plugin.js and plugin/build.
Editorial conclusion
react-native-maps is the sensible default for a React Native app that needs markers, polygons, callouts and tile overlays on iOS and Android, written as ordinary JSX children. It is the wrong choice if you cannot move to React Native 0.81.1 on the New Architecture and need current releases, or if you need truly offline maps on Android without extra configuration. Before adopting it, match your React Native version and architecture against the compatibility tables, and read docs/installation.md for the native setup.
Frequently asked questions
Can React Native use Google Maps through react-native-maps?
Yes. react-native-maps targets Google Maps and MapKit, and MapView accepts provider="google"; custom map styling through googleMapId works only with the Google provider.
How do I install react-native-maps?
The repository keeps its installation steps in docs/installation.md. Check the compatibility table first: on the New Architecture, version 1.26.1 and later need React Native 0.81.1 or newer.
What is react-native-maps?
react-native-maps is a React Native MapView component for iOS and Android in which markers, polygons, polylines, circles, callouts and tile overlays are declared as children of the map.
Is react-native-maps free?
react-native-maps is released under the MIT license, so the library itself can be used and modified without a fee.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/react-native-maps-react-native-maps)Star history chart for your README
[](https://hysenlabs.com/projects/react-native-maps-react-native-maps)Was this useful?