PlatformMap
Weather-agnostic MapLibre shell.
The general map container. It mounts a MapLibre map, resolves the basemap style, and exposes map context (map instance, beforeId, style variant) through usePlatformMap() from @infoplaza/platform/providers. Weather is optional — add host layers as children, or mount WeatherLayers when you need forecast overlays.
import { PlatformMap } from '@infoplaza/platform/components'- Must wrap the map subtree. WeatherLayers and usePlatformMap() only work inside PlatformMap.
- It is a forwardRef to the react-map-gl MapRef, so you can call map methods via ref.
- Style resolution order: style (raw MapLibre URL/object) → mapStyle → mapStyleKey → first entry of mapStyles.
- Call setWorkerUrl for MapLibre 6 before the first map mounts, or basemap tiles will not load.
- The camera stays with MapLibre for the whole pan or zoom, including the release coast. Persist viewState from onMoveEnd.
Required props
| Prop | Type | Default | Description |
|---|---|---|---|
| viewState | Record<string, unknown> | — | Initial camera, plus live constraints such as minZoom, maxZoom, and dragRotate. Pass at least longitude, latitude, and zoom. Longitude, latitude, and zoom apply on mount; persist them from onMoveEnd. Setting a new camera moves the map once it is idle. |
Optional props
| Prop | Type | Default | Description |
|---|---|---|---|
| onMove | (event: unknown) => void | — | Fires on each camera frame, including the release coast. Peer maps stay in sync from here. A live readout can read event.viewState; writing it back on every frame is not required. |
| onMoveEnd | (event: unknown) => void | — | Fires when the gesture, including the release coast, has settled. Use event.viewState to store longitude, latitude, and zoom. |
| syncPeers | boolean | true | When true, panning or zooming this map moves every other mounted map. Set false to keep this camera independent. |
| onClickMap | (event: unknown) => void | — | Fires when the map canvas is clicked. |
| onLoad | (payload: PlatformMapLoadPayload) => void | — | Fires once the map has loaded. Payload includes map, bounds, center, and zoom. |
| children | ReactNode | ((props: { beforeId: string }) => ReactNode) | — | Map children, or a render prop that receives the resolved beforeId (the basemap layer weather should insert under). |
| mapStyleKey | string | — | Selects an entry from mapStyles by key. Built-in keys: 'dark', 'land', 'sea', 'imweather-sea', 'traffic', 'blue-marble'. |
| mapStyles | MapStyle[] | MAP_STYLES | Available basemap styles. Pass [...MAP_STYLES, customStyle] to add your own. |
| onMapStyleKeyChange | (key: string) => void | — | Called when the map asks to switch styles, such as the nowcast Blue Marble hint. Pass this when mapStyleKey is controlled so the hint can update it. |
| mapStyle | BaseMapStyle | — | Explicit style object. Takes precedence over mapStyleKey. Kept mainly for backwards compatibility. |
| style | string | object | null | — | Raw MapLibre style URL or object. When set, it overrides mapStyle / mapStyleKey (escape hatch). |
| styleVariant | 'default' | 'marine' | 'default' | Which variant of the selected style to use. When omitted, WeatherLayers / Providers can switch to marine for wave/ocean models via context. |
| fitBounds | LngLatBoundsLike | — | If set, the map fits these bounds on load and whenever the value changes. |
| fitBoundsOptions | { padding?: number; maxZoom?: number; duration?: number } | { padding: 48, maxZoom: 12, duration: 0 } | Options forwarded to map.fitBounds. Subsequent bound updates use duration 300 unless overridden. |
| ref | React.Ref<MapRef> | — | react-map-gl MapRef. Use getMap() for the underlying MapLibre instance, or call flyTo / fitBounds on the ref. |
MapStyle
A named basemap option with default and marine variants. Import the type from @infoplaza/platform/defaults or @infoplaza/platform/components.
Fields
| Name | Type | Default | Description |
|---|---|---|---|
| key | string | — | Unique id used by mapStyleKey. |
| title | string | — | Human-readable label (for a style picker). |
| styles.default.source | string | object | — | MapLibre style URL or inline style object for land/atmospheric models. |
| styles.default.beforeId | string | — | Basemap layer id to insert weather under. Falls back to 'lakes-transparent' if omitted. |
| styles.marine.source | string | object | — | Style used for marine models (category wave / ocean). |
| styles.marine.beforeId | string | — | beforeId for the marine variant. Built-in marine styles use landcover. |
PlatformMapLoadPayload
Argument passed to onLoad.
Fields
| Name | Type | Default | Description |
|---|---|---|---|
| map | maplibre-gl.Map | — | The loaded MapLibre map instance. |
| bounds | LngLatBounds | — | Current map bounds. |
| center | LngLat | — | Current map center. |
| zoom | number | — | Current zoom level. |
Example
<PlatformMap
viewState={viewState}
onMoveEnd={(event) => setViewState(event.viewState)}
mapStyleKey="dark"
>
<WeatherLayers showHud />
</PlatformMap>