Providers & Hooks

@openweather/maps-react's hooks are thin useSyncExternalStore-style wrappers over @openweather/maps-core's stores — no business state is duplicated in React. They read a CoreMapController from context, established by <MapsProviders> (or its three pieces individually).

`<MapsProviders>`

The convenience wrapper — mounts the settings/controller/layers provider stack in dependency order:

import { MapsProviders } from '@openweather/maps-react';

<MapsProviders controller={controller} destroyControllerOnUnmount={false}>
  <App />
</MapsProviders>;

Prop	Type	Notes
`controller`	`CoreMapController`	The shared controller — from `createCoreMapController`, or `WeatherMapHandle.getController()`
`destroyControllerOnUnmount?`	`boolean`	Defaults to `true`. `<WeatherMap>` passes `false`, since `WeatherMapHandle.destroy()` already destroys the controller it created — letting the provider destroy it too would double-destroy
`locale?` / `theme?` / `units?`		Forwarded to `<SettingsProvider>`, ignored if the controller already has its own settings store (always true for `<MapsProviders>`, which always passes `store={controller.settings}`)
`children`	`ReactNode`

<MapsProviders> always feeds <SettingsProvider> the controller's own settings store, never a second disconnected one — the engine and search controller read controller.settings directly, so anything else would silently desync.

Individual providers

Use these directly if you need finer control than <MapsProviders> gives you:

Provider	Props	Notes
`SettingsProvider`	`apiKey?`, `store?`, `locale?`, `theme?`, `units?`, `children`	`apiKey` is required unless `store` is given; pass `store` to share an existing `SettingsStore`
`MapControllerProvider`	`controller`, `destroyOnUnmount?` (default `true`), `children`
`LayersProvider`	`children`	Reads the controller from `MapControllerProvider`'s context — must be nested inside it

Hooks

Hook	Returns	Notes
`useMapController()`	`CoreMapController`	Escape hatch to the raw controller
`useMapControllerActions()`	action bundle
`useFlyTo()`	`(options: FlyToOptions) => void`
`useLayers()`	`LayersSnapshot`	Active/available layers, from `LayersProvider`
`useLayersActions()`	`{ addLayer, removeLayer, setVisibility, setOrder, setSelectedModel, setLayerModel }`	`setLayerModel(code, modelId)` sets one active layer's model; `setSelectedModel(modelId)` sets the registry-wide default and applies it to every active layer
`useTimeline()`	`TimelineSnapshot`
`useTimelineActions()`	action bundle
`useTimelineScrub()`	scrub helpers
`usePointQuery()`	`PointQueryResult \| null`
`usePointQueryActions()`	action bundle
`usePointQueryAtCoordinate()`	query-at-point helper
`useSearch()`	`SearchSnapshot`
`useSearchActions()`	action bundle
`useSearchAndFlyTo()`	select-and-fly helper
`useSelectedSearchResult()`	`GeocodingResult \| null`
`useSettings()`	`MapSettings`
`useSettingsActions()`	`{ setApiKey, setLocale, setTheme, setUnits, patch, … }`
`usePointFlowStore()`	`PointFlowStore \| null`	The "what happens when the user clicks the map, clicks a pin, or picks a search result" state machine — see `@openweather/maps-ui-core`'s `query-flow` module. `<SimpleMapUI>` wires map clicks straight to `<PointQueryBox>` without going through this store; it remains available for a consumer building a richer click/detail flow of their own
`useOverlays()`	overlay snapshot + actions	Backs `<OverlayToggles>` — see Headless Compounds

Every hook that reads context throws a descriptive error ("X must be used within <X.Provider>" or equivalent) if called outside the relevant provider — the same pattern the compound components use.