Guide · Open source

How to use react-native-maps: setup, markers and tiles

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-native-maps is an open-source MIT-licensed library that adds interactive maps to React Native apps for iOS and Android. This guide shows how the MapView component works, how to add markers and tile layers, and where the README warns about limits. After reading it you will be able to render a map screen and add common map features to it.

react-native-mapsreact-native-maps/react-native-maps · ★ 16k · MIT Install options & downloads

Quick start

1Check your React Native version. Find the matching row in the README compatibility table for your architecture and React Native version.
2Install the package. Follow docs/installation.md in the repository for the install steps for your platform.
3Render a MapView. Add MapView to a screen and set initialRegion with a latitude, longitude and deltas.
4Add markers. Map your data to Marker children, each with a coordinate and optional title and description.
5Add a custom pin or tile layer. Place a named PNG in the platform asset folders and pass it as an image, or add UrlTile or LocalTile as a child.
6Test on a device. Run the app on iOS or Android and check markers, overlays and any animations, especially if you use many custom marker views.

Check compatibility and install the library

Before installing, check the compatibility table in the README against your React Native version. The library is listed for two architectures: Fabric (New Architecture) and Old Architecture. For example, version 1.26.1 and newer require React Native 0.81.1 or higher, while version 1.14.0 to 1.20.1 requires 0.74 or higher on the Old Architecture.

The README does not put installation steps inline. It points to docs/installation.md in the repository, and the example project setup is described in docs/examples-setup.md. Follow those files for the exact install steps for your platform.

Prerequisites named in the source: Node.js and React Native.
Match the library version to your React Native version using the README table.
Installation details are in docs/installation.md.

Render your first map with an initial region

Import the component from the package. The map is shown by the MapView component, and its starting view is set with the initialRegion prop, which takes a latitude, longitude and the latitude and longitude deltas that control zoom.

Use either import MapView from 'react-native-maps' or the CommonJS require form shown in the README.
initialRegion sets the starting view once.
To control the view yourself, pass region together with onRegionChange and keep the region in state.

<MapView
  initialRegion={{
    latitude: 37.78825,
    longitude: -122.4324,
    latitudeDelta: 0.0922,
    longitudeDelta: 0.0421,
  }}
/>

Add markers as child components

Map features such as markers, polygons and tile overlays are written as children of MapView, following React's declarative style. To show a list, map over your data and render one Marker per item. Each marker takes a coordinate, and can take a title and description.

Markers can be dragged when the draggable prop is set. The onDragEnd handler receives an event whose nativeEvent.coordinate holds the new position.

Give each Marker a unique key when rendering a list.
Use the Callout component to add a custom popup to a marker.
Documentation for each component is linked from the README: MapView, Marker, Callout, Polygon, Polyline, Circle, Overlay, Heatmap and Geojson.

<MapView region={this.state.region} onRegionChange={this.onRegionChange}>
  {this.state.markers.map((marker, index) => (
    <Marker
      key={index}
      coordinate={marker.latlng}
      title={marker.title}
      description={marker.description}
    />
  ))}
</MapView>

Use custom marker images or custom marker views

For a custom pin, create a PNG at several resolutions, name it custom_pin, and place it in the Android drawables folder and the iOS assets directory. Then pass it with the image prop. The README notes that passing image binary data with require will not scale well across screen sizes, so the named-asset approach is preferred.

You can also render any React view as the marker. The README warns that custom views have performance implications, and suggests a custom image as the simpler option.

Custom image: image={{uri: 'custom_pin'}} with files in the platform asset folders.
Custom view: place your component as the child of Marker.
Performance: the README advises against many animated custom marker views.

<Marker
  coordinate={{latitude: latitude, longitude: longitude}}
  image={{uri: 'custom_pin'}}
/>

Add a tile overlay from a server or local storage

UrlTile loads tiles from a tile server. The urlTemplate uses {x}, {y} and {z} placeholders that are replaced at runtime. On Android the app needs the INTERNET permission, and on iOS you must configure App Transport Security, as described in the README.

LocalTile reads tiles stored on the device using the xyz tiling scheme, which can support offline use when the tiles for a region are on the device. On Android, LocalTile is an overlay on top of the standard map tiles, so the underlying tiles are still downloaded when online. To prevent that, set mapType to 'none' on Android.

UrlTile props shown in the source: urlTemplate, maximumZ (iOS only), flipY (default false).
LocalTile props shown in the source: pathTemplate and tileSize (usually 256 or 512).
The README links to the OSM Wiki for downloading tiles for offline use.

<MapView region={this.state.region} onRegionChange={this.onRegionChange}>
  <UrlTile
    urlTemplate={this.state.urlTemplate}
    maximumZ={19}
    flipY={false}
  />
</MapView>

Style the map and control the region

For Google Maps, set provider to 'google' and pass a googleMapId to use a styled map published on Google Cloud Platform. The README says this applies to Google Maps on iOS and Android.

To move the map in code, the README says you can use refs and component methods, which can animate to a position, or pass an updated region prop. The MapView can also work with the Animated API, where the region prop is an animated value. The README notes that on Android, marker views are rendered as bitmaps, so some animations may not behave as expected.

Styled Google map: provider="google" with googleMapId.
Move the map with refs, component methods or an updated region prop.
Animated API: the README includes a note about Android limits on animating marker views.

<MapView provider="google" googleMapId="yourStyledMapId" />

What people use it for

Showing a list of locations as markers on a map screen in an iOS or Android app.
Using a custom pin image to match a brand's look on the map.
Drawing a tile layer from a tile server such as OpenStreetMap-style URLs.
Running a map with locally stored tiles for areas where the device may be offline.
Letting users drag a marker and saving its new coordinate.

Frequently asked questions

Is react-native-maps free to use?

The source lists the licence as MIT. The README does not discuss pricing for map providers, so check the terms of any tile server or Google Maps service you connect to.

Which React Native version do I need for react-native-maps?

It depends on the library version and your architecture. The README table lists version 1.26.1 and newer as requiring React Native 0.81.1 or higher on Fabric, and 1.14.0 to 1.20.1 as requiring 0.74 or higher on the Old Architecture. Check the table for your exact version.

Does react-native-maps work for web apps?

No. The README describes it as targeting iOS and Android React Native apps, so it is not meant for web-only projects.

Can I use react-native-maps offline?

The source describes LocalTile, which displays tiles stored on the device using the xyz scheme, and says this is useful for offline use. On Android, set mapType to 'none' if you do not want the underlying tiles downloaded.

Why are my custom markers slow?

The README warns that custom marker views have performance costs, especially with many animated views. It recommends a custom image as a simpler option.

What are the alternatives to react-native-maps?

The source does not name or compare alternative libraries, so this guide cannot make a comparison from it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

react-native-maps suits React Native developers who need a map screen in iOS or Android apps and want map features declared as normal components. It is a weaker fit for web-only projects, very old React Native versions, or apps that must render many animated custom marker views smoothly.

Install options & downloads