tf-react-map-gl
v1.0.2
Published
A React wrapper for MapboxGL-js and overlay API.
Downloads
10
Maintainers
Readme
react-map-gl
react-map-gl provides a React friendly API wrapper around 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.
See the interactive docs at: https://uber.github.io/react-map-gl
Overview
Installation
npm install react-map-gl --save
Usage
import MapGL from 'react-map-gl';
<MapGL width={400} height={400} latitude={37.7577} longitude={-122.4376}
zoom={8} onChangeViewport={(viewport) => {
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.
import ScatterplotOverlay from 'react-map-gl/src/overlays/scatterplot.react';
// ...
<MapGL {...viewport}>
<ScatterplotOverlay
{...viewport}
locations={locations}
dotRadius={4}
globalOpacity={1}
compositeOperation="screen" />
// Add additional overlays here...
])
Built-in Overlays
- ChoroplethOverlay
- ScatterplotOverlay
- DraggablePointsOverlay
- SVGOverlay
- CanvasOverlay
Note: These overlays are currently not compatible with perspective mode.
deck.gl overlays
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 uses webgl-heatmap to create geographic heatmaps.
Example usage:
import HeatmapOverlay from 'react-map-gl-heatmap-overlay';
import cities from 'example-cities';
// ...
render() {
return <MapGL {...viewport}>
return <HeatmapOverlay locations={cities} {...viewport}/>
</MapGL>;
}
Want to create and share your own overlay? Fork the 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.
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 to animate properties. An example:
<Motion style={{
latitude: spring(viewport.latitude, { stiffness: 170, damping: 26, precision: 0.000001 }),
longitude: spring(viewport.longitude, { stiffness: 170, damping: 26, precision: 0.000001 })
}}>
{({ latitude, longitude }) => <MapGL
{...viewport}
latitude={latitude}
longitude={longitude}
mapStyle={mapboxStyle}
/>}
</Motion>
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 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 to save writing this
code yourself.
Development
To develop on this component, install the dependencies and then build and watch the static files.
$ npm install
To serve example app:
$ 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. 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.
CHANGE LOG
See change log