# react-map-gl react-map-gl provides a [React](http://facebook.github.io/react/) friendly API wrapper around [Mapbox GL JS](https://www.mapbox.com/mapbox-gl-js/). A webGL based vector tile mapping library. WARNING: This project is new and the API may change. There also may be Mapbox APIs that haven't yet been exposed. ![react-map-gl-screenshots](https://cloud.githubusercontent.com/assets/499192/11028165/49f41da2-86bc-11e5-85eb-9279621ef971.png) See the interactive docs at: https://uber.github.io/react-map-gl ## Overview ### Installation ``` npm install react-map-gl --save ``` **Note on Bundling:** react-map-gl is extensively tested with `browserify`, however several users have reported issues when bundling their apps using `webpack`. As a first step, please consult the [official mapbox webpack config](https://github.com/mapbox/mapbox-gl-js/blob/master/webpack.config.example.js). There is also some helpful information from in the issues and a [request for help](https://github.com/uber/react-map-gl/issues/112). ### Usage ````js import MapGL from 'react-map-gl'; { const {latitude, longitude, zoom} = viewport; // Optionally call `setState` and use the state to update the map. }} /> ```` ### Using overlays react-map-gl provides an overlay API so you can use the built-in visualization overlays, or create your own. Here's an example of using the build in ScatterplotOverlay. ````js import {ScatterplotOverlay} from 'react-map-gl'; // ... // Add additional overlays here... ]) ```` #### Built-in Overlays 1. ChoroplethOverlay 2. ScatterplotOverlay 3. DraggablePointsOverlay 4. SVGOverlay 5. CanvasOverlay **Note:** These overlays are currently not compatible with perspective mode. ### deck.gl overlays [deck.gl](https://github.com/uber/deck.gl) is a companion module to `react-map-gl` that provide a number of classic data visualization overlays (scatterplots, choropleths etc) implemented in WebGL. These overlays are suitable for large or dynamic data sets, or for use in perspective mode applications #### Third party overlays Third party overlays can also be created. For example, the [heatmap-overlay](https://github.com/vicapow/react-map-gl-heatmap-overlay) uses [webgl-heatmap](https://github.com/vicapow/webgl-heatmap) to create geographic heatmaps. ![heatmap-example](https://cloud.githubusercontent.com/assets/499192/11028150/33f34640-86bc-11e5-9678-3fa1798394d5.gif) Example usage: ````js import HeatmapOverlay from 'react-map-gl-heatmap-overlay'; import cities from 'example-cities'; // ... render() { return return ; } ```` Want to create and share your own overlay? Fork the [react-map-gl-example-overlay](https://github.com/vicapow/react-map-gl-example-overlay) project to get started. ### Perspective Mode Perspective mode is exposed using the `pitch` and `bearing` props (both default to `0`), which will show the map "tilted" `pitch` degrees (overhead being 0 degrees), looking towards `bearing` (0 degrees is north). In addition, the `perspectiveEnabled` prop (default: `false`) will activate mouse handlers that allow the user to change `pitch` and `bearing` using the mouse while holding down the "command" key. If `perspectiveEnabled` is not set to `true` then the user will not be able to change the pitch and bearing, which means that the default props will show an overhead map and only enable standard pan and zoom mouse actions on that map. **Note:** Mapbox-gl-js limits the pitch to 60 degrees. **Note:** When using pitch, several additional fields are passed in the onViewportChange callback, make sure to pass all received props back to the component. **Note:** not all overlays are compatible with perspective mode. For a set of overlays that do work with perspective mode, look at [deck.gl](https://github.com/uber/deck.gl). ### Transitions `react-map-gl` does not expose the transition API for `mapbox-gl-js` since it is designed to be a stateless component. Instead it is recommended to use a separate module like [react-motion](https://github.com/chenglou/react-motion) to animate properties. An example: ```js {({ latitude, longitude }) => } ``` ### ImmutableJS all the things The `mapStyle` property of the `MapGL` as well as several of the built in overlay properties must be provided as [ImmutableJS](https://facebook.github.io/immutable-js/) objects. This allows the library to be fast since computing changes to props only involves checking if the immutable objects are the same instance. ### Use with Redux If you're using redux, it is relatively simple to hook this component up to store state in the redux state tree. The simplest way is to take all properties passed to the `onChangeViewport` function property and add them directly into the store. This state can then be passed back to `react-map-gl` without any transformation. You can use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save writing this code yourself. ## Development To develop on this component, install the dependencies and then build and watch the static files. ```bash $ npm install ``` To serve example app: ```bash $ npm start & $ open "http://localhost:9966/?access_token="`echo $MapboxAccessToken` ``` Where `echo $MapboxAccessToken` returns your Mapbox access token. Once complete, you can view the component in your browser at [localhost:9966](http://localhost:9966). Any changes you make will automatically run the compiler to build the files again. ### Testing Its difficult to write tests for this component beacuse it uses WebGL. There are some tests in `test/` but for the most part, as new features are added, we typically test drive them by running `npm run start` and play with the demos. ### Contributing Contruibutions are welcome. While not necessary, it can be helpful to check with maintainers before opening your PR. Also, you will need to complete a short open source contribution form before your pull request can be accepted. # CHANGE LOG See [change log](https://github.com/uber/react-map-gl/blob/master/CHANGELOG.md)