# react-native-maps [![npm version](https://img.shields.io/npm/v/react-native-maps.svg?style=flat)](https://www.npmjs.com/package/react-native-maps) React Native Map components for iOS + Android ## Contributing This project is being maintained by a small group of people, and any help with issues and pull requests are always appreciated. If you are able and willing to contribute, please read the [guidelines](./CONTRIBUTING.md). ## Installation See [Installation Instructions](docs/installation.md). See [Setup Instructions for the Included Example Project](docs/examples-setup.md). ## Compatibility `react-native-maps` requires `react-native >= 0.64.3`. ## Component API [`` Component API](docs/mapview.md) [`` Component API](docs/marker.md) [`` Component API](docs/callout.md) [`` Component API](docs/polygon.md) [`` Component API](docs/polyline.md) [`` Component API](docs/circle.md) [`` Component API](docs/overlay.md) [`` Component API](docs/heatmap.md) [`` Component API](docs/geojson.md) ## General Usage ```js import MapView from 'react-native-maps'; ``` or ```js var MapView = require('react-native-maps'); ``` This MapView component is built so that features on the map (such as Markers, Polygons, etc.) are specified as children of the MapView itself. This provides an intuitive and react-like API for declaratively controlling features on the map. ### Rendering a Map with an initial region ## MapView ```jsx ``` ### Using a MapView while controlling the region as state ```jsx getInitialState() { return { region: { latitude: 37.78825, longitude: -122.4324, latitudeDelta: 0.0922, longitudeDelta: 0.0421, }, }; } onRegionChange(region) { this.setState({ region }); } render() { return ( ); } ``` ### Rendering a list of markers on a map ```jsx import {Marker} from 'react-native-maps'; {this.state.markers.map((marker, index) => ( ))} ; ``` ### Rendering a Marker with a custom image 1. You need to generate an `png` image with various resolution (lets call them `custom_pin`) - for more information go to [Android](https://developer.android.com/studio/write/resource-manager#import), [iOS](https://developer.apple.com/documentation/xcode/adding-images-to-your-xcode-project) 2. put all images in Android drawables and iOS assets dir 3. Now you can use the following code: ```jsx ``` Note: You can also pass the image binary data like `image={require('custom_pin.png')}`, but this will not scale good with the different screen sizes. ### Rendering a Marker with a custom view Note: This has performance implications, if you wish for a simpler solution go with a custom image (save your self the head ache) ```jsx ``` ### Rendering a custom Marker with a custom Callout ```jsx import {Callout} from 'react-native-maps'; ; ``` ### Draggable Markers ```jsx this.setState({ x: e.nativeEvent.coordinate })} /> ``` ### Using a custom Tile Overlay #### Tile Overlay using tile server ```jsx import {UrlTile} from 'react-native-maps'; ; ``` For Android: add the following line in your AndroidManifest.xml ```xml ``` For IOS: configure [App Transport Security](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) in your app #### Tile Overlay using local tiles Tiles can be stored locally within device using xyz tiling scheme and displayed as tile overlay as well. This is usefull especially for offline map usage when tiles are available for selected map region within device storage. ```jsx import {LocalTile} from 'react-native-maps'; ; ``` For Android: LocalTile is still just overlay over original map tiles. It means that if device is online, underlying tiles will be still downloaded. If original tiles download/display is not desirable set mapType to 'none'. For example: ``` ``` See [OSM Wiki](https://wiki.openstreetmap.org/wiki/Category:Tile_downloading) for how to download tiles for offline usage. ### Overlaying other components on the map Place components that you wish to overlay `MapView` underneath the `MapView` closing tag. Absolutely position these elements. ```jsx render() { return ( ); } ``` ### Customizing the map style Create the json object, or download a generated one from the [google style generator](https://mapstyle.withgoogle.com/). ```jsx // The generated json object mapStyle = [ ... ] render() { return ( ); } ``` For iOS, in addition to providing the `mapStyle` you will need to do the following ```jsx import MapView, { PROVIDER_GOOGLE } from 'react-native-maps' // ... ``` Then add the AirGoogleMaps directory: https://github.com/react-native-maps/react-native-maps/blob/1e71a21f39e7b88554852951f773c731c94680c9/docs/installation.md#ios An unofficial step-by-step guide is also available at https://gist.github.com/heron2014/e60fa003e9b117ce80d56bb1d5bfe9e0 ### MapView Events The `` component and its child components have several events that you can subscribe to. This example displays some of them in a log as a demonstration. ![](http://i.giphy.com/3o6UBpncYQASu2WTW8.gif) ![](http://i.giphy.com/xT77YdviLqtjaecRYA.gif) ### Tracking Region / Location ![](http://i.giphy.com/3o6UBoPSLlIKQ2dv7q.gif) ![](http://i.giphy.com/xT77XWjqECvdgjx9oA.gif) ### Programmatically Changing Region One can change the mapview's position using refs and component methods, or by passing in an updated `region` prop. The component methods will allow one to animate to a given position like the native API could. ![](http://i.giphy.com/3o6UB7poyB6YJ0KPWU.gif) ![](http://i.giphy.com/xT77Yc4wK3pzZusEbm.gif) ### Changing the style of the map ![](http://i.imgur.com/a9WqCL6.png) ### Arbitrary React Views as Markers ![](http://i.giphy.com/3o6UBcsCLoLQtksJxe.gif) ![](http://i.giphy.com/3o6UB1qGEM9jYni3KM.gif) ### Using the MapView with the Animated API The `` component can be made to work with the Animated API, having the entire `region` prop be declared as an animated value. This allows one to animate the zoom and position of the MapView along with other gestures, giving a nice feel. Further, Marker views can use the animated API to enhance the effect. ![](http://i.giphy.com/xT77XMw9IwS6QAv0nC.gif) ![](http://i.giphy.com/3o6UBdGQdM1GmVoIdq.gif) Issue: Since android needs to render its marker views as a bitmap, the animations APIs may not be compatible with the Marker views. Not sure if this can be worked around yet or not. Markers' coordinates can also be animated, as shown in this example: ![](http://i.giphy.com/xTcnTelp1OwGPu1Wh2.gif) ![](http://i.giphy.com/xTcnT6WVpwlCiQnFW8.gif) ### Polygon Creator ![](http://i.giphy.com/3o6UAZWqQBkOzs8HE4.gif) ![](http://i.giphy.com/xT77XVBRErNZl3zyWQ.gif) ### Other Overlays So far, ``, ``, and `` are available to pass in as children to the `` component. ![](http://i.giphy.com/xT77XZCH8JpEhzVcNG.gif) ![](http://i.giphy.com/xT77XZyA0aYeOX5jsA.gif) ### Gradient Polylines (iOS MapKit only) Gradient polylines can be created using the `strokeColors` prop of the `` component. ![](https://i.imgur.com/P7UeqAm.png?1) ### Default Markers Default markers will be rendered unless a custom marker is specified. One can optionally adjust the color of the default marker by using the `pinColor` prop. ![](http://i.giphy.com/xT77Y0pWKmUUnguHK0.gif) ![](http://i.giphy.com/3o6UBfk3I58VIwZjVe.gif) ### Custom Callouts Callouts to markers can be completely arbitrary react views, similar to markers. As a result, they can be interacted with like any other view. Additionally, you can fall back to the standard behavior of just having a title/description through the ``'s `title` and `description` props. Custom callout views can be the entire tooltip bubble, or just the content inside of the system default bubble. To handle press on specific subview of callout use `` with `onPress`. See `Callouts.js` example. ![](http://i.giphy.com/xT77XNePGnMIIDpbnq.gif) ![](http://i.giphy.com/xT77YdU0HXryvoRqaQ.gif) ### Image-based Markers Markers can be customized by just using images, and specified using the `image` prop. ![](http://i.imgur.com/mzrOjTR.png) ### Draggable Markers Markers are draggable, and emit continuous drag events to update other UI during drags. ![](http://i.giphy.com/l2JImnZxdv1WbpQfC.gif) ![](http://i.giphy.com/l2JIhv4Jx6Ugx1EGI.gif) ### Lite Mode ( Android ) Enable lite mode on Android with `liteMode` prop. Ideal when having multiple maps in a View or ScrollView. ![](http://i.giphy.com/qZ2lAf18s89na.gif) ### On Poi Click (Google Maps Only) Poi are clickable, you can catch the event to get its information (usually to get the full detail from Google Place using the placeId). ![](https://media.giphy.com/media/3480VsCKnHr31uCLU3/giphy.gif) ### Animated Region The MapView can accept an `AnimatedRegion` value as its `region` prop. This allows you to utilize the Animated API to control the map's center and zoom. ```jsx import MapView, { AnimatedRegion, Animated } from 'react-native-maps'; getInitialState() { return { region: new AnimatedRegion({ latitude: LATITUDE, longitude: LONGITUDE, latitudeDelta: LATITUDE_DELTA, longitudeDelta: LONGITUDE_DELTA, }), }; } onRegionChange(region) { this.state.region.setValue(region); } render() { return ( ); } ``` ### Animated Marker Position Markers can also accept an `AnimatedRegion` value as a coordinate. ```jsx import Mapview, { AnimatedRegion, MarkerAnimated } from 'react-native-maps'; getInitialState() { return { coordinate: new AnimatedRegion({ latitude: LATITUDE, longitude: LONGITUDE, }), }; } componentWillReceiveProps(nextProps) { const duration = 500 if (this.props.coordinate !== nextProps.coordinate) { if (Platform.OS === 'android') { if (this.marker) { this.marker.animateMarkerToCoordinate( nextProps.coordinate, duration ); } } else { this.state.coordinate.timing({ ...nextProps.coordinate, useNativeDriver: true, // defaults to false if not passed explicitly duration }).start(); } } } render() { return ( { this.marker = marker }} coordinate={this.state.coordinate} /> ); } ``` ### Take Snapshot of map ```jsx import MapView, { Marker } from 'react-native-maps'; getInitialState() { return { coordinate: { latitude: LATITUDE, longitude: LONGITUDE, }, }; } takeSnapshot () { // 'takeSnapshot' takes a config object with the // following options const snapshot = this.map.takeSnapshot({ width: 300, // optional, when omitted the view-width is used height: 300, // optional, when omitted the view-height is used region: {..}, // iOS only, optional region to render format: 'png', // image formats: 'png', 'jpg' (default: 'png') quality: 0.8, // image quality: 0..1 (only relevant for jpg, default: 1) result: 'file' // result types: 'file', 'base64' (default: 'file') }); snapshot.then((uri) => { this.setState({ mapSnapshot: uri }); }); } render() { return ( { this.map = map }}> Take Snapshot ); } ``` ### Zoom to Specified Markers Pass an array of marker identifiers to have the map re-focus. ![](http://i.giphy.com/3o7qEbOQnO0yoXqKJ2.gif) ![](http://i.giphy.com/l41YdrQZ7m6Dz4h0c.gif) ### Zoom to Specified Coordinates Pass an array of coordinates to focus a map region on said coordinates. ![](https://cloud.githubusercontent.com/assets/1627824/18609960/da5d9e06-7cdc-11e6-811e-34e255093df9.gif) ### Troubleshooting #### My map is blank - Make sure that you have [properly installed](docs/installation.md) react-native-maps. - Check in the logs if there is more informations about the issue. - Try setting the style of the MapView to an absolute position with top, left, right and bottom values set. - Make sure you have enabled Google Maps API in [Google developer console](https://console.developers.google.com/apis/library) ```javascript const styles = StyleSheet.create({ map: { ...StyleSheet.absoluteFillObject, }, }); ``` ```jsx ``` #### Inputs don't focus - When inputs don't focus or elements don't respond to tap, look at the order of the view hierarchy, sometimes the issue could be due to ordering of rendered components, prefer putting MapView as the first component. Bad: ```jsx ``` Good: ```jsx ``` #### Children Components Not Re-Rendering Components that aren't declared by this library (Ex: Markers, Polyline) must not be children of the MapView component due to MapView's unique rendering methodology. Have your custom components / views outside the MapView component and position absolute to ensure they only re-render as needed. Example: Bad: ```jsx ``` Good: ```jsx ``` Source: https://github.com/react-native-maps/react-native-maps/issues/1901 #### Crashing with EXC_BAD_ACCESS on iOS when switching apps `` using Apple Maps in `mapType: "standard"` will sometimes crash when you background the app or switch into another app. This is only an issue in XCode using Metal API Validation, and won't happen in production. To eliminate this problem even while debugging in XCode, go to `Edit Scheme... -> Run (Debug) -> Diagnostics` and uncheck `Metal -> API Validation`. (h/t [@Simon-TechForm](https://github.com/Simon-TechForm)). Source: https://github.com/react-native-maps/react-native-maps/issues/3957#issuecomment-924161121 #### onRegionChangeComplete() callback is called infinitely If changing the state in `onRegionChangeComplete` is called infinitely, add a condition to limit these calls to occur only when the region change was done as a result of a user's action. ```javascript onRegionChangeComplete={ (region, gesture) => { // This fix only works on Google Maps because isGesture is NOT available on Apple Maps if (!gesture.isGesture) { return; } // You can use dispatch({ type: "map_region", payload: { mapRegion: region }}); // if using useReducer // setMapRegionState(region); // if using useState }} ``` Source: https://github.com/react-native-maps/react-native-maps/issues/846#issuecomment-1210079461 ## License Copyright (c) 2017 Airbnb Licensed under the The MIT License (MIT) (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://raw.githubusercontent.com/airbnb/react-native-maps/master/LICENSE Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

	Stars	Issues	Version	Updated	Created
react-map-gl	7,552	76	7.1.7	4 months ago	9 years ago
react-mapbox-gl	1,888	265	5.1.1	3 years ago	8 years ago
react-native-google-maps-directions	180	8	2.1.1	5 years ago	7 years ago
react-native-maps	14,740	69	1.14.0	5 days ago	8 years ago

react-map-gl vs react-mapbox-gl vs react-native-google-maps-directions vs react-native-maps

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past