Documentation

Map

The map stack is split across four packages. New integrations should use PlatformMap with WeatherLayers, which already mounts providers, events, and the layer overlay. The composed APIs below are for hosts that need to wire the stack themselves. See API request counts and token credits in the maps platform example.

Components

@infoplaza/platform/components

MapLibre shell, packaged weather stack, and control HUD.
import {
  PlatformMap,
  WeatherLayers,
  MapControlHud,
  MapControlTimebar,
  MapControlLegend,
} from '@infoplaza/platform/components'

Also exported as types: PlatformMapProps, PlatformMapLoadPayload, WeatherLayersProps, MapControlHudProps, MapControlTimebarProps, MapControlLegendProps, MapStyle, BaseMapStyle, MapStyleVariant.

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

PropTypeDefaultDescription
viewStateRecord<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

PropTypeDefaultDescription
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.
syncPeersbooleantrueWhen 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.
childrenReactNode | ((props: { beforeId: string }) => ReactNode)—Map children, or a render prop that receives the resolved beforeId (the basemap layer weather should insert under).
mapStyleKeystring—Selects an entry from mapStyles by key. Built-in keys: 'dark', 'land', 'sea', 'imweather-sea', 'traffic', 'blue-marble'.
mapStylesMapStyle[]MAP_STYLESAvailable 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.
mapStyleBaseMapStyle—Explicit style object. Takes precedence over mapStyleKey. Kept mainly for backwards compatibility.
stylestring | 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.
fitBoundsLngLatBoundsLike—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.
refReact.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

NameTypeDefaultDescription
keystring—Unique id used by mapStyleKey.
titlestring—Human-readable label (for a style picker).
styles.default.sourcestring | object—MapLibre style URL or inline style object for land/atmospheric models.
styles.default.beforeIdstring—Basemap layer id to insert weather under. Falls back to 'lakes-transparent' if omitted.
styles.marine.sourcestring | object—Style used for marine models (category wave / ocean).
styles.marine.beforeIdstring—beforeId for the marine variant. Built-in marine styles use landcover.

PlatformMapLoadPayload

Argument passed to onLoad.

Fields

NameTypeDefaultDescription
mapmaplibre-gl.Map—The loaded MapLibre map instance.
boundsLngLatBounds—Current map bounds.
centerLngLat—Current map center.
zoomnumber—Current zoom level.

Example

<PlatformMap
  viewState={viewState}
  onMoveEnd={(event) => setViewState(event.viewState)}
  mapStyleKey="dark"
>
  <WeatherLayers showHud />
</PlatformMap>

WeatherLayers

Packaged weather stack for use under PlatformMap.

Mounts Providers, map events, the Deck.gl layer pipeline (LayerComposer + LayerOverlay), and optionally MapControlHud. Use this instead of wiring Providers / MapEventsProvider / LayerComposer by hand unless you need a custom composition.

import { WeatherLayers } from '@infoplaza/platform/components'
  • Must be rendered as a child of PlatformMap. It calls usePlatformMap() for beforeId.
  • Fetches the models catalog internally via GET /api/platform/models. Mount PlatformAuth on your server.
  • Do not wrap PlatformMap in an outer Providers as well — Providers already lives inside WeatherLayers.
  • Toggle weather on a feature map by mounting or unmounting WeatherLayers.
  • Sync a graph or an external ship marker from onHover. Pass the hour back as TimeseriesGraph hoverTimestamp. The host owns that cursor; WeatherLayers does not draw a marker or move the timebar.

Required props

None.

Optional props

PropTypeDefaultDescription
weatherConfigWeatherConfig{}Initial weather selection. Omitted fields use packaged defaults (gfs / temperature / latest; member and level are inferred). Optional onModelFallback receives { models, element, bounds } and returns a slug when the selected model is not visible.
modelsConfigModelsConfig—Controls the internal models request. Set basePath if PlatformAuth is not mounted at /api/platform.
handler'simple' | 'demand' | 'nowcast' | 'tiles'—Map event handler. When omitted, forecast and nowcast models use tiles. Observations, tropical storms, grades, and other non-forecast catalogs use simple. Anything else uses demand.
showHudbooleanfalseWhen true, renders MapControlHud (model / element / time / legend / zoom controls).
hudPropsMapControlHudProps—Props forwarded to MapControlHud when showHud is true.
interleavedbooleantrueWhen true, weather layers are inserted into the MapLibre style under beforeId so labels and borders stay on top. When false, Deck.gl draws as an overlay on top of the map.
controllerbooleantrueForwarded to the Deck.gl overlay. When true, the overlay participates in pointer interaction and picking.
mapIndexnumber0Label for this map in a multi-map layout, passed through to Providers. Each WeatherLayers keeps its own timeline whatever the value.
timestampsnumber[]—Unix timestamps for the timebar when no layer frames are loaded. A fetched forecast replaces this list. Pass at least two values; a single frame stays hidden.
maxForecastHoursnumber—Hours from now to keep. Later frames drop off the timebar, playback, and preload together. Omit it to show the full catalog horizon (about 7, 10, or 16 days, depending on the model).
childrenReactNode—Extra content rendered inside Providers, alongside the overlay and HUD. Place MapControlTimebar and MapControlLegend here when you are not using showHud.
onHover(hover: WeatherLayerHover | null) => void—Pointer sample over the weather layers: { lat, lon, value, timestamp, direction? }. timestamp is the committed timebar frame in unix seconds. value is the decoded raster in the active element’s units, or null when the pick has no finite raster. direction (degrees it comes from) is the picked vector’s own, or else the topmost wind layer’s. element, level, unit and decimals describe the picked layer, and pressure is added when the map also shows a pressure element. Null when the pointer leaves the map. Does not seek the timebar. The overlay picks on hover while onHover is set or tooltip is on. A pickable contour under the cursor can hide the raster; lat and lon still emit and value is null. During playback, value can be the crossfade while timestamp stays on the committed frame.
tooltipbooleantrueValue tooltip that follows the cursor: the value and unit under the pointer, rounded like the grid values, plus pressure and wind direction when the map shows them. Hidden for nowcast, over points without data, and while the map moves. Set false to draw your own tooltip from onHover.

WeatherConfig

Initial weather selection passed to Providers.

Fields

NameTypeDefaultDescription
modelstring'gfs'Initial model slug.
elementstring | null'temperature'Initial weather element. Omit it for temperature. null selects no element and does not fetch a layer.
runstring'latest'Initial model run.
memberstring—Ensemble member. Inferred from the model when omitted.
levelstring—Vertical level. Inferred from the element when omitted.
hideLayersstring[][]Layer slugs to hide from the weather stack.
modelsModelInfo[]—Deprecated. Models are fetched internally. If provided, they take precedence over the fetched catalog.

ModelsConfig

Options for the internal GET ${basePath}/models and GET ${basePath}/nowcast-info requests.

Fields

NameTypeDefaultDescription
basePathstring'/api/platform'Public path where PlatformAuth is mounted. Catalog requests go to ${basePath}/models and ${basePath}/nowcast-info.

WeatherLayerHover

Pointer sample from WeatherLayers onHover. Import the type from @infoplaza/platform/components.

Fields

NameTypeDefaultDescription
latnumber—Latitude under the pointer.
lonnumber—Longitude under the pointer.
valuenumber | null—Decoded raster in the active element’s units, or null when the pick has none.
timestampnumber | null—Committed timebar frame, unix seconds. Null before a series is loaded.
directionnumber | null—Degrees the flow comes from (0–360). The picked vector’s own direction, or else the topmost wind (vector) layer on the map. Null over a calm or uncovered point. Omitted when neither the pick nor the map has a wind layer.
elementstring—Element of the picked layer, such as temperature. Omitted when the pick has no layer.
levelstring—Level of the picked layer, such as 850hPa. Omitted when the layer has none.
unitstring | null—Unit of the picked layer, from the layer or its legend. Null when it has none.
decimalsnumber—The picked layer’s grid-values Decimals setting, so a tooltip can match the on-map labels.
pressure{ value: number | null; unit: string | null }—Pressure under the pointer when the map also shows a pressure element besides the picked one. value is null where pressure has no data. Omitted when pressure is the picked element.

Example

const [cursor, setCursor] = useState<WeatherLayerHover | null>(null)

<PlatformMap
  viewState={viewState}
  onMoveEnd={(event) => setViewState(event.viewState)}
>
  <WeatherLayers showHud onHover={setCursor} />
</PlatformMap>

MapControlHud

Built-in map controls for model, element, time, legend, and zoom.

The control chrome that sits on top of the map: model / run / member pickers, element groups, timebar, legend, layer settings, info, and zoom. A nowcast element shows its period menu under the active element button, the same way level does. Prefer enabling it through WeatherLayers (showHud) unless you are composing the stack yourself.

import { MapControlHud } from '@infoplaza/platform/components'
  • Must be rendered inside Providers (WeatherMap context). WeatherLayers already provides that when showHud is true.
  • Layout is device-aware: mobile uses a compact layer control and MapControlMobileTimebar; desktop uses the full timebar and a vertical layer panel.
  • The bar uses model type when that type is forecast, nowcast, or climate, and format otherwise. Forecast and nowcast use the play bar. The observations element uses a scrubber. Climate models use a month and period bar.

Required props

None.

Optional props

PropTypeDefaultDescription
preloadOnGrabbooleantrueWhile the timebar thumb is held, tile layers preload the rest of the run. Set false to load only the frame under the thumb.
skipUnavailableFramesbooleanfalseTimebar playback jumps over frames without tiles (red on the bar), including a red tail at the end of the run, and keeps looping. Leave false to stop playback at the first unavailable frame.
autostartbooleanfalseThe timebar starts playing on its own once the next frame is loaded. Useful for embeds and widgets.
timeSkipnumber—Frames the timebar moves per previous or next step (buttons, arrow keys, mouse wheel), wrapping at either end. Unset steps one frame. Playback is not affected.

Example

<WeatherLayers
  showHud
  hudProps={{ skipUnavailableFrames: true }}
/>

// Composed stack (inside Providers, under PlatformMap):
<MapControlHud />

MapControlTimebar

Play bar for the active model, or for a host-supplied timestamp list.

The same bar MapControlHud shows: a forecast or nowcast play bar, an observations scrubber, or a climate month bar. Place it yourself when you do not want the rest of the HUD. It reports the selected unix timestamp through onChange.

import { MapControlTimebar } from '@infoplaza/platform/components'
  • Must be a child of WeatherLayers or another Providers tree. It reads the weather model and the timestamp context.
  • Position it with className. The bar is full width; absolute placement overlays the map.
  • With no active layer, pass timestamps on WeatherLayers. Those frames are used until a forecast fetch returns its own series.
  • Pass a stable onChange. It runs when the timestamp changes, including the first frame, scrub, step, and playback.
  • The bar stays hidden until the model catalog resolves a forecast, nowcast, or climate kind, and until there are at least two frames.

Required props

None.

Optional props

PropTypeDefaultDescription
classNamestring—Merged onto the bar root. Use it to position the bar on the map.
onChange(timestamp: number) => void—Called with the selected unix timestamp whenever it changes.
languagestring—Locale used to format tick labels. Defaults inside each bar.
timezonestring—IANA timezone for tick labels. Defaults to UTC.
smallbooleanfalseShorter bar, used by the HUD in a multi-map layout.
playButtonbooleantrueShows the play control on the forecast and nowcast bars.
preloadOnGrabbooleantrueWhile the thumb is held, tile layers preload the rest of the run. Set false to load only the frame under the thumb.
skipUnavailableFramesbooleanfalsePlayback jumps over frames without tiles (red on the bar), including a red tail at the end of the run, and keeps looping. Leave false to stop playback at the first unavailable frame. Nowcast already plays through.
autostartbooleanfalseStarts playing on its own once the next playable frame is loaded. Playback then waits for later frames as it goes.
timeSkipnumber—Frames to move per previous or next step (buttons, arrow keys, mouse wheel), wrapping at either end. Unset steps one frame. Playback is not affected.
options{ acceptedMinutes?: string[] }—Which minutes get a tick. The HUD passes the active element timebar options.

Example

<PlatformMap viewState={viewState} onMoveEnd={onMoveEnd}>
  <WeatherLayers
    weatherConfig={{ element: null }}
    timestamps={frames}
  >
    <MapControlTimebar
      className="ip:absolute ip:bottom-4 ip:inset-x-4"
      onChange={(timestamp) => setFrame(timestamp)}
    />
  </WeatherLayers>
</PlatformMap>

MapControlLegend

Gradient legend for the active weather layer.

The legend bar from the HUD, without the details sheet. It reads the active layer legend when legends is omitted, and renders nothing on a bare basemap.

import { MapControlLegend } from '@infoplaza/platform/components'
  • Must be a child of WeatherLayers or another Providers tree so it can read legend context.
  • Position it with className. The details sheet stays on MapControlHud.

Required props

None.

Optional props

PropTypeDefaultDescription
legendsLegendInfo[]—Gradient rows. When omitted, the legend uses the values published by the active layer.
classNamestring—Merged onto the legend root.
heightnumber28Row height in pixels.
smallbooleanfalseDrops the rounded corners used on larger layouts.

Example

<WeatherLayers weatherConfig={{ element: 'temperature' }}>
  <MapControlLegend className="ip:absolute ip:top-16 ip:right-4" />
</WeatherLayers>

Providers

@infoplaza/platform/providers

Context tree and hooks for map, models, weather selection, layer settings, and display flags. WeatherLayers mounts Providers for you.
import {
  Providers,
  useProviders,
  usePlatformMap,
  usePlatformMapContext,
  ModelsProvider,
  useModels,
  useModelsContext,
  WeatherMapProvider,
  useWeatherMap,
  useTimestampMap,
  LayerSettingsProvider,
  useLayerSettings,
  DisplaySettingsProvider,
  useDisplaySettings,
} from '@infoplaza/platform/providers'

Also exported: PlatformMapContext, ModelsContext, WeatherMapContext, and types PlatformMapContextValue, PlatformMapStyleVariantName.

Providers

Composed weather context tree for the map stack.

Mounts Redux timestamps, models fetch, weather state, legend values, layer settings, and display settings. WeatherLayers already includes this. Use Providers yourself only when composing LayerComposer / MapEventsProvider by hand.

import { Providers } from '@infoplaza/platform/providers'
  • When mounted under PlatformMap, Providers switches the basemap to the marine variant for wave/ocean models.
  • Do not wrap PlatformMap in Providers if you also use WeatherLayers — that would nest two provider trees.
  • Fetches GET {basePath}/models and GET {basePath}/nowcast-info on mount. Mount PlatformAuth on your server.

Required props

PropTypeDefaultDescription
childrenReactNode—Map overlay, HUD, or other consumers of weather context.

Optional props

PropTypeDefaultDescription
weatherConfigWeatherConfig{}Initial weather selection. Omitted fields use gfs / temperature / latest; member and level are inferred.
modelsConfigModelsConfig—Controls the internal models request. Set basePath if PlatformAuth is not mounted at /api/platform.
mapIndexnumber0Label for this map in a multi-map layout, read back with useProviders. Each Providers has its own timestamp store, so maps never share a timeline.
maxForecastHoursnumber—Hours from now to keep on the timebar, playback, and preload. Omit it to show the full catalog horizon. WeatherLayers forwards this prop.

Example

<PlatformMap viewState={viewState} onMoveEnd={onMoveEnd}>
  <Providers
    weatherConfig={{ model: 'optimal', element: 'temperature' }}
  >
    <MapEventsProvider>
      {(mapComponents) => (
        <LayerComposer beforeId={beforeId} mapComponents={mapComponents}>
          {({ layers }) => <LayerOverlay layers={layers} interleaved />}
        </LayerComposer>
      )}
    </MapEventsProvider>
    <MapControlHud />
  </Providers>
</PlatformMap>

useProviders

Reads every provider value in one call.

Convenience hook for composed hosts that need models, weather, legend, layer settings, display settings, the map timestamp, and mapIndex together. Throws if any of those providers is missing.

import { useProviders } from '@infoplaza/platform/providers'
  • Must be used inside Providers (or WeatherLayers).

Arguments

None.

Returns

NameTypeDefaultDescription
mapIndexnumber—Active map index from MapIndexProvider.
modelsModelsContextValue—Same as useModels(): { models, loading, error }.
weatherWeatherContextValue—Same as useWeatherMap().
legend{ legends, setLegends }—Legend values used by MapControlHud.
layerSettingsLayerSettingsContextValue—Same as useLayerSettings().
displaySettingsDisplaySettingsContextValue—Same as useDisplaySettings().
timestampTimestampContextValue—Same as useTimestampMap().

Example

const { weather, models, layerSettings } = useProviders()
if (models.loading) return null
return <span>{weather.model} · {models.models.length} models</span>

usePlatformMap

MapLibre instance and style context from PlatformMap.

Use this to add host sources/layers, call flyTo, or read the beforeId that weather layers insert under. Throws when used outside PlatformMap.

import { usePlatformMap } from '@infoplaza/platform/providers'
  • Must be used under PlatformMap. map is null until the MapLibre map has loaded.

Arguments

None.

Returns

NameTypeDefaultDescription
mapmaplibre-gl.Map | null—The loaded MapLibre map, or null before onLoad.
beforeIdstring—Basemap layer id weather should insert under. Falls back to lakes-transparent.
styleVariant'default' | 'marine'—Active style variant.
setStyleVariant(variant: 'default' | 'marine') => void—Switch variant. Providers already does this for marine models.

Example

function FlyToAmsterdam() {
  const { map } = usePlatformMap()
  return (
    <button
      type="button"
      disabled={!map}
      onClick={() => map?.flyTo({ center: [4.9041, 52.3676], zoom: 10 })}
    >
      Fly to Amsterdam
    </button>
  )
}

usePlatformMapContext

Nullable PlatformMap context.

Same value as usePlatformMap, but returns null outside PlatformMap instead of throwing. Used internally by Providers for marine style sync.

import { usePlatformMapContext } from '@infoplaza/platform/providers'

Arguments

None.

Returns

NameTypeDefaultDescription
(return)PlatformMapContextValue | null—Map context, or null when there is no PlatformMap ancestor.

Example

const ctx = usePlatformMapContext()
ctx?.setStyleVariant('marine')

ModelsProvider

Fetches the weather models catalog.

Loads GET {basePath}/models and GET {basePath}/nowcast-info once. Nowcast is prepended as one model when the catalog has elements. Each product is one element; its periods are a control on that element. A nowcast failure leaves the forecast list in place. Exposes { models, loading, error, basePath }. Already mounted inside Providers. Use it directly only if you need the catalog without the rest of the weather tree.

import { ModelsProvider } from '@infoplaza/platform/providers'

Required props

PropTypeDefaultDescription
childrenReactNode—Consumers of useModels / useModelsContext.

Optional props

PropTypeDefaultDescription
basePathstring'/api/platform'Public path where PlatformAuth is mounted.

Example

<ModelsProvider basePath="/api/platform">
  <ModelCount />
</ModelsProvider>

useModels

Weather models catalog from ModelsProvider.

Throws outside ModelsProvider. Prefer this when the catalog is required; use useModelsContext when the component can render without it.

import { useModels } from '@infoplaza/platform/providers'

Arguments

None.

Returns

NameTypeDefaultDescription
modelsModelInfo[]—Fetched catalog. Empty until the request succeeds.
loadingboolean—True while the models request is in flight.
errorError | null—Set when the models request fails.
basePathstring—Normalized auth mount path. Nowcast frames request ${basePath}/nowcast-layers.

Example

function ModelCount() {
  const { models, loading, error } = useModels()
  if (loading) return <span>Loading models…</span>
  if (error) return <span>Failed to load models</span>
  return <span>{models.length} models available</span>
}

useModelsContext

Nullable models catalog.

Same as useModels, but returns null outside ModelsProvider instead of throwing.

import { useModelsContext } from '@infoplaza/platform/providers'

Arguments

None.

Returns

NameTypeDefaultDescription
(return)ModelsContextValue | null—{ models, loading, error, basePath }, or null outside ModelsProvider.

WeatherMapProvider

Weather selection state and derived layer info.

Holds the active model, element, run, member, and level, and derives modelInfo, elementInfo, and layersInfo. Reads the catalog from ModelsProvider unless weatherConfig.models is passed. Already mounted inside Providers.

import { WeatherMapProvider } from '@infoplaza/platform/providers'
  • Should sit under ModelsProvider so the catalog is available.
  • weatherConfig.models is deprecated; the fetched catalog takes over when it is omitted.

Required props

PropTypeDefaultDescription
childrenReactNode—HUD, events, and other weather consumers.

Optional props

PropTypeDefaultDescription
modelstring'gfs'Initial model slug.
elementstring | null'temperature'Initial weather element. Omit it for temperature. null selects no element and does not fetch a layer.
runstring'latest'Initial model run.
memberstring—Ensemble member. Inferred from the model when omitted.
levelstring—Vertical level. Inferred from the element when omitted.
hideLayersstring[][]Layer slugs to hide from the weather stack.
modelsModelInfo[]—Deprecated. If provided, takes precedence over ModelsProvider.
maxForecastHoursnumber—Hours from now to keep. Exposed on useWeatherMap() so layer handlers can trim frames. Omit it to show the full catalog horizon.

Example

<ModelsProvider>
  <WeatherMapProvider model="optimal" element="wind">
    <MapControlHud />
  </WeatherMapProvider>
</ModelsProvider>

useWeatherMap

Current weather selection and derived layer info.

Throws outside WeatherMapProvider. Use this to read or change the active model, element, run, member, and level, or to inspect layersInfo for the HUD and event handlers.

import { useWeatherMap } from '@infoplaza/platform/providers'

Arguments

None.

Returns

NameTypeDefaultDescription
modelstring—Active model slug.
elementstring | null—Active element slug, or null when no element is selected.
modelRunstring—Active run (for example latest).
modelMemberstring | null—Active ensemble member.
modelLevelstring | null—Active vertical level.
setModel / setElement / setModelRun / setModelMember / setModelLevelfunction—Selection setters.
modelsModelInfo[]—Catalog used by this provider.
modelInfoModelInfo | null—Resolved available model (may fall back if the slug is missing).
elementInfoElementInfo | null—Active element, including layers and HUD options.
layersInfoWeatherLayersInfo | null—Resolved layer stack for the current selection.
hideLayersstring[]—Layer slugs hidden via config.
maxForecastHoursnumber | undefined—Display horizon in hours from now, when the host set one.

Example

const { model, setModel, elementInfo } = useWeatherMap()
setModel('gfs')

useTimestampMap

Current map timestamp and the loaded time series.

Reads the clock owned by the map. Forecast handlers set the series and the initial timestamp when a model loads; the timebar updates it while the user scrubs or plays. Call setTimestamp to seek. Throws outside Providers.

import { useTimestampMap } from '@infoplaza/platform/providers'
  • Must be used inside WeatherLayers or Providers. WeatherLayers renders children inside that tree. A sibling of WeatherLayers cannot call this hook.
  • Hosts should use timestamp, timestamps, timestampsInfo, setTimestamp, and timebarPlaying.
  • setTimestamps, preloadedData, setPreloadedData, and addUrlToPreload stay on TimestampContextValue for the layer pipeline. Do not call them from host code.

Arguments

None.

Returns

NameTypeDefaultDescription
timestampnumber | null—Active unix timestamp, or null before the model series has loaded.
timestampsnumber[] | null—Unix timestamps for the current model, or null before they load.
timestampsInfoTimestampInfo[]—Timebar steps for the current series, including whether each step is loaded. When no layer frames are loaded, this is the timestamps list passed to WeatherLayers.
setTimestamp(timestamp: number) => void—Seek the map to a unix timestamp from the loaded series.
timebarPlayingboolean—True while the timebar is playing.

Example

function MapTime() {
  const { timestamp, timestamps, setTimestamp } = useTimestampMap()
  const next = timestamps?.find((value) => timestamp != null && value > timestamp)

  return (
    <button
      type="button"
      disabled={next == null}
      onClick={() => next != null && setTimestamp(next)}
    >
      {timestamp}
    </button>
  )
}

<PlatformMap viewState={viewState} onMoveEnd={onMoveEnd}>
  <WeatherLayers showHud>
    <MapTime />
  </WeatherLayers>
</PlatformMap>

LayerSettingsProvider

Per-layer rendering settings (image, contours, particles, …).

Holds user-tunable settings for each rendering type and persists them to storage. LayerComposer reads getLayerState(layer) to decide what to draw. Already mounted inside Providers.

import { LayerSettingsProvider } from '@infoplaza/platform/providers'

Required props

PropTypeDefaultDescription
childrenReactNode—Layer composer, HUD layer panel, or other settings consumers.

Optional props

None.

Example

<LayerSettingsProvider>
  <LayerComposer mapComponents={mapComponents}>
    {({ layers }) => <LayerOverlay layers={layers} />}
  </LayerComposer>
</LayerSettingsProvider>

useLayerSettings

Read and write per-layer rendering settings.

Throws outside LayerSettingsProvider. Use getLayerState(layer) for the merged flat settings object that connectors consume. Per-bucket getters and setters (image, values, contour, …) write only that layer.

import { useLayerSettings } from '@infoplaza/platform/providers'
  • state and actions are the legacy global defaults, used for layers that have not been configured individually.
  • Settings persist in local storage (state-layer-settings-v1).

Arguments

None.

Returns

NameTypeDefaultDescription
stateLayerSettingsState—Merged default + global settings (not per-layer).
actionsLegacyLayerActions—Global setters (image opacity, particle count, barb density, …).
getLayerState(layer) => LayerSettingsState—Merged settings for a specific layer. Used by LayerComposer.
getImageState / setImageState / …function—Per-bucket reads and writes for IMAGE_V2, VALUES, CONTOURS, CONTOURGEOJSON, DIRECTIONS, BARBS, and GRADES.

Example

const { getLayerState, setImageState } = useLayerSettings()
const settings = getLayerState(layer)
setImageState(layer, { imageOpacity: 0.8 })

DisplaySettingsProvider

HUD display flags (advanced layer settings, frame skip).

Persists advanceLayerSettings and frameSkip. LayerComposer uses frameSkip to keep the last valid timestamp visible while the next one loads. Already mounted inside Providers.

import { DisplaySettingsProvider } from '@infoplaza/platform/providers'

Required props

PropTypeDefaultDescription
childrenReactNode—Layer composer or HUD settings consumers.

Optional props

None.

useDisplaySettings

Read and write display flags.

Throws outside DisplaySettingsProvider.

import { useDisplaySettings } from '@infoplaza/platform/providers'

Arguments

None.

Returns

NameTypeDefaultDescription
advanceLayerSettingsbooleanfalseWhen true, the HUD shows advanced layer controls.
setAdvanceLayerSettings(value: boolean) => void—Persist advanced layer settings.
frameSkipbooleanfalseWhen true, LayerComposer keeps showing the last loaded timestamp while the current one is missing.
setFrameSkip(value: boolean) => void—Persist frame skip.
state{ advanceLayerSettings, frameSkip }—Snapshot of both flags.

Layers

@infoplaza/platform/layers

Deck.gl pipeline: compose weather descriptors into layers, then overlay them on the MapLibre map.
import {
  LayerComposer,
  LayerOverlay,
} from '@infoplaza/platform/layers'

Overlay is an alias of LayerOverlay. Deep imports @infoplaza/platform/layers/composer and @infoplaza/platform/layers/overlay are also available.

LayerComposer

Turns weather map components into Deck.gl layers.

Reads mapComponents from MapEventsProvider, picks connectors by rendering type (IMAGE_V2, VALUES, PARTICLES, BARBS, DIRECTIONS, CONTOURS, HIGHLOW, CONTOURGEOJSON, STORMTRACKS, PLOT, GRADES), and applies LayerSettingsProvider state. Pass the resulting layers to LayerOverlay. WeatherLayers already wires this.

import { LayerComposer } from '@infoplaza/platform/layers'
  • Must be rendered inside Providers (needs useLayerSettings, useDisplaySettings, and timestamp context).
  • beforeId should match PlatformMap / usePlatformMap().beforeId so labels stay above weather.
  • When frameSkip is on, the last valid timestamp and last rendered layers are kept while the next payload loads.

Required props

PropTypeDefaultDescription
children(args: { layers: Layer[] }) => ReactNode—Render prop. layers is the Deck.gl layer list to pass to LayerOverlay.

Optional props

PropTypeDefaultDescription
mapComponentsRecord<number, unknown[]>—Timestamp → layer descriptors from MapEventsProvider. When omitted or empty, no weather layers are produced (unless frameSkip keeps the previous list).
beforeIdstring—MapLibre layer id forwarded to connectors so interleaved weather inserts under labels and borders.

Example

<MapEventsProvider>
  {(mapComponents) => (
    <LayerComposer beforeId={beforeId} mapComponents={mapComponents}>
      {({ layers }) => (
        <LayerOverlay layers={layers} interleaved beforeId={beforeId} />
      )}
    </LayerComposer>
  )}
</MapEventsProvider>

LayerOverlay

Deck.gl overlay on the MapLibre map.

Mounts a MapLibreOverlay with the layers from LayerComposer. When interleaved is true, weather is inserted into the basemap style under beforeId so place names stay on top. Overlay is the same component under another name.

import { LayerOverlay } from '@infoplaza/platform/layers'
  • Must be a child of PlatformMap (or any react-map-gl Map). It uses useMap / useControl.
  • import { Overlay } from "@infoplaza/platform/layers" is an alias of LayerOverlay.
  • Also exported from @infoplaza/platform/layers/overlay and @infoplaza/platform/layers/composer.

Required props

PropTypeDefaultDescription
layersLayer[]—Deck.gl layers from LayerComposer (or your own).

Optional props

PropTypeDefaultDescription
interleavedbooleantrueWhen true, layers are inserted into the MapLibre style. When false, Deck.gl draws on top of the map.
beforeIdstring—MapLibre layer id to insert weather under. Required for correct interleaved order; if it cannot be resolved, interleaved layers are skipped rather than drawn above labels.
controllerboolean—Forwarded to the Deck.gl overlay. When true, the overlay participates in pointer interaction and picking.

Example

<LayerOverlay
  layers={layers}
  interleaved
  controller
  beforeId={beforeId}
/>

Events

@infoplaza/platform/events

Fetches weather layer payloads and textures for the current map view. MapEventsProvider picks a handler from the active model unless you override it.
import MapEventsProvider, {
  useEventHandlerType,
  DemandEventsProvider,
  SimpleEventsProvider,
  NowcastEventsProvider,
  TilesEventsProvider,
} from '@infoplaza/platform/events'
import type { EventHandlerType } from '@infoplaza/platform/events'

EventHandlerType is 'simple' | 'demand' | 'nowcast' | 'tiles'.

MapEventsProvider

Fetches weather layer payloads and textures for the current view.

Chooses a handler (tiles, simple, demand, or nowcast) from the active model unless you pass handler, then loads layer URLs and textures keyed by timestamp. The render-prop argument is the mapComponents object LayerComposer expects. WeatherLayers already mounts this.

import MapEventsProvider from '@infoplaza/platform/events'
  • Must be inside Providers (weather + timestamps) and PlatformMap (MapLibre map).
  • Also available as a named export: import { MapEventsProvider } from "@infoplaza/platform/events".
  • Handler resolution when handler is omitted: forecast and nowcast models → tiles; the observations element on a forecast, tropical storms, grades, and other non-forecast catalogs → simple; otherwise demand. Pass handler="simple" or handler="demand" to keep a full-domain loader.

Required props

PropTypeDefaultDescription
children(mapComponents: Record<number, unknown[]>) => ReactNode—Render prop. mapComponents maps unix timestamps to layer descriptors for LayerComposer.

Optional props

PropTypeDefaultDescription
handler'simple' | 'demand' | 'nowcast' | 'tiles'—Force a handler. When omitted, useEventHandlerType() picks one from the active model and element.

EventHandlerType

Handler ids exported from @infoplaza/platform/events.

Fields

NameTypeDefaultDescription
tiles'tiles'—Visible tiles for forecast and nowcast models. Playback blends on one map.
demand'demand'—Viewport-driven fetches, debounced on map move. Used when the host passes handler="demand".
simple'simple'—Fixed viewport URL, preloads all timestamps. Used for the observations element, tropical storms, grades, and other catalogs that are not forecasts.
nowcast'nowcast'—Nowcast texture pipeline with viewport-driven fetches on map move.

Example

<MapEventsProvider handler="demand">
  {(mapComponents) => (
    <LayerComposer beforeId={beforeId} mapComponents={mapComponents}>
      {({ layers }) => <LayerOverlay layers={layers} interleaved />}
    </LayerComposer>
  )}
</MapEventsProvider>

useEventHandlerType

Resolves which map event handler to use.

Returns the override if you pass one; otherwise inspects the active model (type, format, region category) and element slug. Must be used inside WeatherMapProvider.

import { useEventHandlerType } from '@infoplaza/platform/events'

Optional arguments

PropTypeDefaultDescription
override'simple' | 'demand' | 'nowcast' | 'tiles'—Force this handler instead of resolving from the model.

Returns

NameTypeDefaultDescription
(return)'simple' | 'demand' | 'nowcast' | 'tiles'—Handler id. Defaults to demand when no rule matches.

Example

const handler = useEventHandlerType()
const forced = useEventHandlerType('simple')

DemandEventsProvider

Viewport-driven forecast layer fetches.

Loads layer URLs from the current map bounds, debounced on move, then fetches forecast textures per timestamp. MapEventsProvider selects this when no forecast, nowcast, or simple rule matches. Prefer MapEventsProvider unless you need to pin this handler.

import { DemandEventsProvider } from '@infoplaza/platform/events'
  • Must be inside Providers and a react-map-gl Map (uses useMap).
  • Same children render prop as MapEventsProvider. No handler prop — this is the handler.

Required props

PropTypeDefaultDescription
children(mapComponents: Record<number, unknown[]>) => ReactNode—Same as MapEventsProvider children.

Optional props

None.

Example

<DemandEventsProvider>
  {(mapComponents) => (
    <LayerComposer mapComponents={mapComponents}>
      {({ layers }) => <LayerOverlay layers={layers} />}
    </LayerComposer>
  )}
</DemandEventsProvider>

SimpleEventsProvider

Fixed-viewport forecast fetches with full preload.

Builds layer URLs without tracking map move, and preloads all timestamps. MapEventsProvider selects this for the observations element on a forecast, for regional catalogs that are not forecasts, and for tropical storms and grades. Prefer MapEventsProvider unless you need to pin this handler.

import { SimpleEventsProvider } from '@infoplaza/platform/events'

Required props

PropTypeDefaultDescription
children(mapComponents: Record<number, unknown[]>) => ReactNode—Same as MapEventsProvider children.

Optional props

None.

Example

<SimpleEventsProvider>
  {(mapComponents) => (
    <LayerComposer mapComponents={mapComponents}>
      {({ layers }) => <LayerOverlay layers={layers} />}
    </LayerComposer>
  )}
</SimpleEventsProvider>

NowcastEventsProvider

Viewport-driven nowcast texture pipeline.

Like demand, but uses the nowcast texture loader. MapEventsProvider uses the tiles handler for nowcast. Pass handler="nowcast" to pin this full-domain loader.

import { NowcastEventsProvider } from '@infoplaza/platform/events'
  • Must be inside Providers and a react-map-gl Map (uses useMap).
  • Frame timestamps come from GET {basePath}/nowcast-layers.

Required props

PropTypeDefaultDescription
children(mapComponents: Record<number, unknown[]>) => ReactNode—Same as MapEventsProvider children.

Optional props

None.

Example

<NowcastEventsProvider>
  {(mapComponents) => (
    <LayerComposer mapComponents={mapComponents}>
      {({ layers }) => <LayerOverlay layers={layers} />}
    </LayerComposer>
  )}
</NowcastEventsProvider>

Deprecated

Still exported and supported, but not recommended for new integrations.

BaseMap

Deprecated

Weather-aware map shell. Prefer PlatformMap + WeatherLayers for new integrations.

A thin wrapper around PlatformMap that reads the active model from weather context and switches the basemap to the marine variant for wave/ocean models. It must be rendered inside Providers. Still supported for the hand-wired stack; new hosts should use PlatformMap with WeatherLayers instead.

import { BaseMap } from '@infoplaza/platform/components'
  • Deprecated. Use PlatformMap + WeatherLayers for new integrations.
  • Must be rendered inside Providers. It calls useWeatherMap() to resolve the marine style variant.
  • Does not accept styleVariant, onLoad, fitBounds, or fitBoundsOptions — those stay on PlatformMap.
  • Marine switching is automatic: model category wave or ocean uses the marine variant; everything else uses default.

Required props

PropTypeDefaultDescription
viewStateRecord<string, unknown>—Initial camera and live constraints. Same as PlatformMap.viewState.

Optional props

PropTypeDefaultDescription
onMove(event: unknown) => void—Same as PlatformMap.onMove.
onMoveEnd(event: unknown) => void—Same as PlatformMap.onMoveEnd.
onClickMap(event: unknown) => void—Same as PlatformMap.onClickMap.
childrenReactNode | ((props: { beforeId: string }) => ReactNode)—Typically the composed weather stack: MapEventsProvider, LayerComposer, LayerOverlay, and MapControlHud. The render-prop form receives beforeId.
mapStyleKeystring—Same as PlatformMap.mapStyleKey.
mapStylesMapStyle[]MAP_STYLESSame as PlatformMap.mapStyles.
mapStyleBaseMapStyle—Same as PlatformMap.mapStyle.
stylestring | object | null—Same as PlatformMap.style.
syncPeersbooleantrueSame as PlatformMap.syncPeers.

Example

<Providers>
  <BaseMap viewState={viewState} onMoveEnd={onMoveEnd} mapStyleKey="dark">
    {({ beforeId }) => (
      <>
        <MapEventsProvider>
          {(mapComponents) => (
            <LayerComposer beforeId={beforeId} mapComponents={mapComponents}>
              {({ layers }) => (
                <LayerOverlay layers={layers} interleaved controller />
              )}
            </LayerComposer>
          )}
        </MapEventsProvider>
        <MapControlHud />
      </>
    )}
  </BaseMap>
</Providers>