v7 is a complete rewrite of the library. It is redesigned to be fast, lightweight, fully typed, to behave the same and expose the same APIs as the wrapped map library, and to provide the maximum compatibility with third-party plugins. To take advantages of these new features, you need to make some changes to your code that was previously depending on react-map-gl v5 and v6.
If you are using react-map-gl controls (
Marker,Popup,NavigationControletc.) with deck.gl'sContextProvider, do not upgrade to this version. The old approach no longer works with v7. We are moving the support for this use case to a new project that does not depend on mapbox.
mapbox-gl (or a compatible fork) to your package.json. react-map-gl no longer lists a specific map renderer in its dependencies, so you are free to use it with Mapbox v1, v2 or Maplibre.viewport-mercator-project (an alias of @math.gl/web-mercator) is no longer a dependency. You can still install the library on the side as a utility for viewport-related math, but it's no longer required.InteractiveMap and StaticMap are removed. Instead, import Map.setRTLTextPlugin is removed. Use the Map component's RTLTextPlugin prop (default enabled).MapController is removed. v7.0 has removed its own implementation of user input handling in favor of the native handlers. If you are using a custom implementation of MapController, check if the native handlers offer options to address your application's needs.MapContext and useMapControl are removed. Check out the new API useMap and useControl.HTMLOverlay, CanvasOverlay and SVGOverlay) are removed. Check out this example for implementing similar controls in your own application.LinearInterpolator and FlyToInterpolator are removed. Use map.easeTo() and map.flyTo() instead, see this example.mapboxApiAccessToken is now mapboxAccessTokenmapboxApiUrl is now baseApiUrlpreventStyleDiffing (default false) is replaced with styleDiffing (default true)mapStyle should be explicitly specified. The default value has changed from "mapbox://styles/mapbox/light-v9" to an empty style.style instead:widthheightvisibleonViewportChange, onViewStateChange and onInteractionStateChange are removed. You can either use Map as an uncontrolled component with the new initialViewState prop, or if you need to manage the camera state externally (e.g. in Redux), use the onMove callback instead. See examples in state management.transition* props are removed. Use map.easeTo() and map.flyTo() instead, see this example.mapOptions is removed. Almost all of the options for the native Map class are exposed as props. onHover is removed. Use onMouseMove or onMouseEnter.getCursor is removed as part of the effort to get Map behave the same as the native component. To set the cursor, use the cursor prop. Follow this example to change cursor on hover.touchAction and eventRecognizerOptions are removed. Check out the cooperativeGestures prop.capture* props are removed.*label props are removed. Use Map's locale prop.MapContext is now an official API. The experimental _MapContext export will be removed in a future release.react-virtualized-auto-sizer is no longer a dependency.const CONTROLLER_OPTS = {
dragPan: {inertia: 0},
dragRotate: {inertia: 0},
touchZoom: {inertia: 0}
};
<MapGL {...CONTROLLER_OPTS} ... />Source and Layer components no longer expose imperative methods via ref as part of the migration to functional components. This is to comply with the pattern recommended by the latest React.sourceRef.getSource(), it can be replaced with mapRef().getMap().getSource(sourceId).layerRef.getLayer(), it can be replaced with mapRef().getMap().getLayer(layerId).InteractiveMap's maxPitch prop is changed to 85 from 60.mapbox-gl v2 introduced a breaking change to the build system. Transpiling it may result in a crash in the production build with the message m is not defined. Find solutions in this thread.onChangeViewport is removed, use onViewportChange insteadImmutable.js is no longer a dependencyexperimental.MapControls is removed, use MapController insteadInteractiveMap's mapControls prop is renamed to controllerinteractive property on the layer styles. Use the interactiveLayerIds prop to specify which layers are clickable.v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed or removed features, a few breaking changes could not be avoided.
StaticMap and InteractiveMap. InteractiveMap is the default export, and designed to be as compatible as possible with the v2 default component.onChangeViewport callback now includes width and height.The viewport parameter passed to the onChangeViewport callback now includes width and height. Application code that composed the viewport with width and height may have to be updated. Please double check your render code if you relied on this behavior.
// BAD: 'width' and 'height' below will be overridden by what's in the 'viewport' object
<ReactMapGL width={500} height={400} {...viewport} />
// GOOD: 'width' and 'height' below will override the values in 'viewport'
<ReactMapGL {...viewport} width={500} height={400} />DraggablePointsOverlay, ChoroplethOverlay, ScatterplotOverlay), have been moved to examples. Most users are now using mapbox styles or deck.gl layers and removing these overlays reduces the size of the react-map-gl library for the majority of users that don't need them. If you still use them, simply copy the overlay source file(s) into your application.react-map-gl component to automatically sync with the map viewport.fitBounds utility functionThe fitBounds utility has been moved to the math.gl library. The function can now be called as follows:
import WebMercatorViewport from 'viewport-mercator-project';
const viewport = new WebMercatorViewport({width: 600, height: 400});
const bound = viewport.fitBounds(
[[-73.9876, 40.7661], [-72.9876, 41.7661]],
{padding: 20, offset: [0, -40]}
);
// => bounds: instance of WebMercatorViewport
// {longitude: -73.48760000000007, latitude: 41.268014439447484, zoom: 7.209231188444142}We have started to deprecate a few React props. In all the cases below, the old props will still work (you'll get a warning in the console), but they will likely be removed in the next major version of react-map-gl so you should start using the new props as soon as possible.
| Old Prop | New Prop |
|---|---|
onChangeViewport(<viewport>) | onViewportChange(<viewport>) |
onHoverFeatures(<features>) | onHover(<event>) |
onClickFeatures(<features>) | onClick(<event>) |
perspectiveEnabled [default: false] | dragRotate [default: true] |
v2 is API compatible with v1, however if you are still using v1 of react-map-gl, make sure that you first upgrade:
node version to v4 or higherreact version to 15.4 or higher.Background: mapbox-gl 0.31.0 introduced a hard dependency on Node >= v4.
(Upgrading from 0.6.x)
HTMLOverlay, CanvasOverlay, SVGOverlay etc) are now named exports. They previously had to be imported via their relative source paths:// v1.0
import MapGL, {SVGOverlay} from 'react-map-gl';
// v0.6
import MapGL from 'react-map-gl';
import SVGOverlay from 'react-map-gl/src/api-reference/svg-overlay';.onViewportChanged will now contain additional state fields (tracking not only pitch and bearing needed for perspective mode, but also transient information about how the projection is being changed by the user).mapState in your app store whenever it changes and then pass it back to the component rather than trying to keep track of individual fields (like longitude, latitude and zoom).