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
Option | Description | Default |
---|---|---|
accessKeys | Type: {id: string, secret: string} (required)Xweather client id and secret keys used to create an Account instance. |
|
options | Type: 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. |
|
children | Type: ReactNode ()Components that have access to the map controller context. |
|
strategy | Type: MapStrategyType (required)The underlying mapping library to use (MapLibre, Mapbox, Google, Leaflet). |
|
map | Type: any (required)The map instance created using the selected provider's API. |
|
onLoad | Type: () => void ()Triggered when the map view and all required resources have loaded and the map has been rendered initially. |
|
onUnload | Type: () => void ()Triggered when the map view has been removed from the DOM. |
|
onResize | Type: () => void ()Triggered when the map view container has been resized. |
|
onZoom | Type: () => void ()Triggered when the map's current zoom level is changing. This event is triggered repeatedly during any zoom animation. |
|
onZoomStart | Type: () => void ()Triggered when the map is about to change the current zoom level. |
|
onZoomEnd | Type: () => void ()Triggered when the map has completed changing the current zoom level and any animations have ended. |
|
onMove | Type: () => void ()Triggered when the map's viewport is changing. This event is triggered repeatedly during any move animation. |
|
onMoveStart | Type: () => void ()Triggered when the map is about to change its current viewport. |
|
onMoveEnd | Type: () => void ()Triggered when the map has completed changing its viewport and any animations have ended. |
|
onLoadStart | Type: () => void ()Triggered when any active data source on the map begins requesting data. |
|
onLoadComplete | Type: () => void ()Triggered when all active data sources have completed data requests. |
|
onSourceAdd | Type: () => void ()Triggered when a data source has been added to the map. |
|
onLayerAdd | Type: () => void ()Triggered when a layer has been added to the map. |
|
onSourceRemove | Type: () => void ()Triggered when a data source has been removed from the map. |
|
onLayerRemove | Type: () => void ()Triggered when a layer has been removed from the map. |
|
onClick | Type: (event: Event) => void ()Triggered when a click or tap interaction has been received by the map. |
|
onDoubleClick | Type: (event: Event) => void ()Triggered when a click or tap interaction has been received by the map. |
|
onMouseDown | Type: () => void ()Triggered when the mouse is pressed within the map. |
|
onMouseUp | Type: () => void ()Triggered when the mouse is released within the map. |
|
onMouseOver | Type: () => void ()Triggered when the mouse is moved within the map. |
|
onMouseOut | Type: () => void ()Triggered when the mouse is moved out of the map. |
|
onMouseMove | Type: () => 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
Option | Description | Default |
---|---|---|
controller | Type: AnyMapController (required)The map controller instance that provides access to all MapsGL functionality and methods. |
|
zoomIn | Type: () => void ()Increases current map zoom level by 1. |
|
zoomOut | Type: () => void ()Decreases current map zoom level by 1. |
|
toggleLegend | Type: () => void ()Additional map controller options. Review the MapsGL Map Controller (opens in a new tab) reference documentation for more information about the available options. |
|