Introduction
These docs are for
Looking for an old version?
react-map-gl is a suite of React components for Mapbox GL JS-compatible libraries.
| Library | Description |
|---|---|
| MapLibre | An open fork of mapbox-gl v1, that can be used without a mapbox token. |
| Mapbox GL JS v1 | The previous version of mapbox GL JS. This version is free open source and can be used with non-mapbox basemaps without a mapbox token. |
| Mapbox GL JS v2 | The latest version of Mapbox GL JS. Note that version 2 is not free open source, and a mapbox token is required and billable events are generated even if you do not use mapbox hosted basemaps. |
| Other mapbox-gl forks | It may be possible to use react-map-gl with other mapbox forks, but this is not a supported use case. Minor PRs to enable other forks to be used may be accepted. |
For basemaps:
- You can load map data from Mapbox's own service.
- You can create and host your own map data using one of the many open source tools.
New to react-map-gl? Get Started
Want to contribute? See our Developer Guide
Design Philosophy
react-map-gl was first created by Uber's Visualization team, where Mapbox was used as a component to build powerful web tools such as geospatial analytics and self-driving data visualization. To manage the complexity of these applications, we fully embrace React and reactive programming.
The stock mapbox-gl APIs are imperative. That is, you instruct the map to do something (for example, map.flyTo), and it will execute the command at its own pace.
This does not scale when we have many components that need to synchronize with each other. We sometimes render two maps side by side, and when the user interacts with one, update both cameras. We draw React UI outside of the map container, that moves with the camera. We also render WebGL graphic overlays on top of the map, most notably with deck.gl. In these use cases, in order for all components to synchronize correctly, they must have their shared states managed by React. We might store the source of truth in a parent component state, or Redux store, or hooks, and let it propagate down to the map as well as its peers.
Ultimately, in the spirit of the reactive programming paradigm, data always flows down. As long as the map manages its own state, as mapbox-gl is designed to do, we risk the components going out of sync.
react-map-gl creates a fully reactive wrapper for mapbox-gl. The Map component can be fully controlled, that is, the map's camera would never deviate from the props that it's assigned. Read more about this core behavior in state management.
Limitations
In v7.0, react-map-gl was fully rewritten to better align its API with the underlying Mapbox GL JS library. Wherever the reactive usage patterns permits, the wrapper's props and methods are 1:1 mappings to their native API equivelants.
It is possible to call the native methods directly from the Map instance obtained via getMap. However, doing so may result in the map's state to deviate from its props. For example, calling map.setMaxZoom directly will cause the map's constraint settings to differ from the value of the maxZoom prop. Generally speaking, calling a native method is disencouraged if the same thing can be achieved through the React interface. If a third-party plugin does so, then it may lead to some unexpected behaviors.