react-map-gl

To call imperative Map methods (like those provided by MapLibre), you can use a React ref or the useMap hook. When using a ref, ensure you use the MapRef type to access the safe subset of methods that do not conflict with React props.

Warning: Some native Map methods are intentionally hidden from the MapRef object to prevent state mismatches between React props and the underlying map state. For example, setStyle() is hidden because you should use the mapStyle prop instead. If you must access these hidden native methods, use getMap() to retrieve the underlying native instance.

import * as React from 'react';
import {useRef, useCallback} from 'react';
import {Map} from 'react-map-gl/maplibre';
import type {MapRef} from 'react-map-gl/maplibre';

function App() {
  const mapRef = useRef<MapRef>();

  const onMapLoad = useCallback(() => {
    // mapRef.current provides access to safe Map methods
    mapRef.current?.on('move', () => {
      // do something
    });
  }, []);

  return <Map ref={mapRef} onLoad={onMapLoad} ... />;
}

Upgrading to v3 involves several breaking changes regarding component structure, overlay placement, and utility functions.

Node Version Requirement

When building react-map-gl, you must use Node >= v6.4.0. This requirement does not apply if you are using a prebuilt version of the library.

Map Component Changes

The Map component is now split into two components:

1. StaticMap
2. InteractiveMap (the default export, designed for compatibility with v2).

Viewport Callback Changes

The viewport parameter in the onChangeViewport callback now includes width and height. If your application manually composes width and height with the viewport object, you must ensure the component props are ordered so that your explicit dimensions override the values inside the viewport object.

Overlay Changes

• Relocation: Less frequently used overlays like DraggablePointsOverlay, ChoroplethOverlay, and ScatterplotOverlay have been moved to examples. If needed, copy their source files into your project.
• Rendering: Overlays must now be rendered as children of the main react-map-gl component to ensure automatic synchronization with the map viewport.

fitBounds Utility

The fitBounds utility has moved to the math.gl library. You should now use WebMercatorViewport from viewport-mercator-project to handle bounds fitting.

// v3 Viewport Prop Ordering
// 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} />

To add custom data and native Mapbox layers to your map, use the Source and Layer components. The Source component defines the data (e.g., a GeoJSON FeatureCollection), and the Layer component defines how that data is styled using the Mapbox style specification. This approach works for both Mapbox and MapLibre implementations.

import * as React from 'react';
import Map, {Source, Layer} from 'react-map-gl/maplibre';
import type {CircleLayer} from 'react-map-gl/maplibre';
import type {FeatureCollection} from 'geojson';

const geojson: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [-122.4, 37.8]
      },
      properties: {title: '915 Front Street, San Francisco, California'}
    }
  ]
};

const layerStyle: CircleLayer = {
  id: 'point',
  type: 'circle',
  paint: {
    'circle-radius': 10,
    'circle-color': '#007cbf'
  }
};

function App() {
  return (
    <Map
      initialViewState={{
        longitude: -122.45,
        latitude: 37.78,
        zoom: 14
      }}>
      <Source id="my-data" type="geojson" data={geojson}>
        <Layer {...layerStyle} />
      </Source>
    </Map>
  );
}