MapsGL Usage
Map Controller Provider

MapsGL Map Controller Provider

The MapsGLMapControllerProvider integrates with the MapsGL Map Controller (opens in a new tab) to provide easy access to a map controller instance througout your application. Child components can interact with a map controller via the useMapsGLMapControllerContext hook. All MapsGL-related data, such as data sources, weather layers, custom layers, and animation timeline information, is managed by the map controller. If you are using any of the MapsGL-related components (MapsGLTimelineControl, MapsGLSearchControl, MapsGLLayerControl) or any of the , you must use the MapsGLMapControllerProvider to provide the map controller context.

Usage

To use the MapsGLMapControllerProvider you must pass your Xweather account credentials, a map instance, and a chosen map strategy. Here's an example of setting it up with a Mapbox map:

// Create a variable to hold the access keys
const accessKeys = {
  id: process.env.XWEATHER_ID,
  secret: process.env.XWEATHER_SECRET
};
 
export default function App() {
  // Create a state variable to hold the map instance once it's created
  const [map, setMap] = useState<mapboxgl.Map | null>(null);
  // Create a ref to hold the map container element
  const containerRef = useRef<HTMLDivElement>(null);
 
  useEffect(() => {
    // Create the map instance using third-party mapping library, in this case Mapbox
    mapboxgl.accessToken = YOUR_MAPBOX_KEY;
    const mapEl = new mapboxgl.Map({
      container: containerRef.current || '',
      style: 'mapbox://styles/mapbox/light-v9',
      center: [-74.5, 40],
      zoom: 3,
    });
    // Set the map in state
    setMap(mapEl);
  }, []);
 
  return (
    // accessKeys, strategy, and map instance are required
   <MapsGLMapControllerProvider 
        accessKeys={accessKeys}
        strategy="mapbox" 
        map={map}>
      {/* Any components that need access to the map context go here */}
    </MapsGLMapControllerProvider>
 
    <div ref={containerRef} id="map"></div>
  );
}

Here is an example of using some of the event based props, onLoad and onClick, to add custom functionality with the flyTo method provided by Mapbox on inital map load and a click events:

export default function App() {
  // ... existing map setup code ...
 
  const handleMapControllerLoad = () => {
    // Get user's location and animate to it using the Mapbox flyTo method
    if (navigator.geolocation) {
      navigator.geolocation.getCurrentPosition((position) => {
        map?.flyTo({
          center: [position.coords.longitude, position.coords.latitude],
          zoom: 10,
          essential: true
        });
      });
    }
  };
 
  // Animate on map click to the coordinates using the Mapbox flyTo method
  const handleMapClick = (event: Event) => {
        const data = event as {
        coord?: {
            lat: number;
            lon: number;
        }};
 
        if (data?.coord) {
            const { lat, lon } = data.coord;
 
            map?.flyTo({
                center: [lon, lat],
                essential: true,
                zoom: 9
            });
        }
    };
 
  return (
    <MapsGLMapControllerProvider 
        strategy="mapbox" 
        map={map} 
        onLoad={handleMapControllerLoad}
        onClick={handleMapClick} />
 
    <div ref={containerRef} id="map"></div>
  );
}

Provider API reference

OptionDescriptionDefault
accessKeysType: {id: string, secret: string} (required)Xweather client id and secret keys used to create an Account instance.
optionsType: Record<string, any> ()Additional map controller options. Review the MapsGL Map Controller (opens in a new tab) reference documentation for more information about the available options.
childrenType: ReactNode ()Components that have access to the map controller context.
strategyType: MapStrategyType (required)The underlying mapping library to use (MapLibre, Mapbox, Google, Leaflet).
mapType: any (required)The map instance created using the selected provider's API.
onLoadType: () => void ()Triggered when the map view and all required resources have loaded and the map has been rendered initially.
onUnloadType: () => void ()Triggered when the map view has been removed from the DOM.
onResizeType: () => void ()Triggered when the map view container has been resized.
onZoomType: () => void ()Triggered when the map's current zoom level is changing. This event is triggered repeatedly during any zoom animation.
onZoomStartType: () => void ()Triggered when the map is about to change the current zoom level.
onZoomEndType: () => void ()Triggered when the map has completed changing the current zoom level and any animations have ended.
onMoveType: () => void ()Triggered when the map's viewport is changing. This event is triggered repeatedly during any move animation.
onMoveStartType: () => void ()Triggered when the map is about to change its current viewport.
onMoveEndType: () => void ()Triggered when the map has completed changing its viewport and any animations have ended.
onLoadStartType: () => void ()Triggered when any active data source on the map begins requesting data.
onLoadCompleteType: () => void ()Triggered when all active data sources have completed data requests.
onSourceAddType: () => void ()Triggered when a data source has been added to the map.
onLayerAddType: () => void ()Triggered when a layer has been added to the map.
onSourceRemoveType: () => void ()Triggered when a data source has been removed from the map.
onLayerRemoveType: () => void ()Triggered when a layer has been removed from the map.
onClickType: (event: Event) => void ()Triggered when a click or tap interaction has been received by the map.
onDoubleClickType: (event: Event) => void ()Triggered when a click or tap interaction has been received by the map.
onMouseDownType: () => void ()Triggered when the mouse is pressed within the map.
onMouseUpType: () => void ()Triggered when the mouse is released within the map.
onMouseOverType: () => void ()Triggered when the mouse is moved within the map.
onMouseOutType: () => void ()Triggered when the mouse is moved out of the map.
onMouseMoveType: () => void ()Triggered when the mouse is moved while inside the map. This event is triggered every time the mouse is moved within the map bounds.

Context API Reference

OptionDescriptionDefault
controllerType: AnyMapController (required)The map controller instance that provides access to all MapsGL functionality and methods.
zoomInType: () => void ()Increases current map zoom level by 1.
zoomOutType: () => void ()Decreases current map zoom level by 1.
toggleLegendType: () => void ()Additional map controller options. Review the MapsGL Map Controller (opens in a new tab) reference documentation for more information about the available options.