From 4138d7a4dc22c9fbb3357d001b3f6c0089aa4837 Mon Sep 17 00:00:00 2001 From: Dan Leech Date: Tue, 20 Oct 2026 11:24:58 +0100 Subject: [PATCH 1/2] Document that map:ready fires before the base map style loads --- docs/api.md | 18 +++++++++++++++++- docs/api/context.md | 2 ++ src/config/events.js | 6 ++++-- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/api.md b/docs/api.md index 56f6fa1f..04652b56 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1056,7 +1056,9 @@ interactiveMap.on('app:continue', ({ pluginStates, mapState }) => { ### `map:ready` -Emitted when the underlying map is ready and initial app state (style and size) has settled. +Emitted when the underlying map instance has been created and initial app state (style and size) has settled. The map is created once the layout and safe zone have been calculated, so the initial padding, bounds and centre already account for the interface. + +The base map style may still be loading when `map:ready` fires. Wait for [`map:loaded`](#maploaded) before adding sources or layers to the underlying map. **Payload:** @@ -1076,6 +1078,20 @@ interactiveMap.on('map:ready', ({ map, mapStyleId, mapSize }) => { --- +### `map:loaded` + +Emitted once, when the initial base map style has loaded. Emitted after `map:ready`. Sources and layers can be added to the underlying map from this point. + +**Payload:** None + +```js +interactiveMap.on('map:loaded', () => { + console.log('Base map loaded') +}) +``` + +--- + ### `map:stylechange` Emitted when the map style finishes loading after a style change. diff --git a/docs/api/context.md b/docs/api/context.md index dd658438..fcef4a0f 100644 --- a/docs/api/context.md +++ b/docs/api/context.md @@ -96,6 +96,8 @@ Current map state, including: } ``` +`mapState.isMapReady` is `true` once the map instance has been created (`map:ready`). The base map style may still be loading at that point; check `mapProvider.isBaseMapReady()` before adding sources or layers to the underlying map. + --- ### `services` diff --git a/src/config/events.js b/src/config/events.js index bcbf511c..6272b4ac 100644 --- a/src/config/events.js +++ b/src/config/events.js @@ -178,11 +178,13 @@ export const EVENTS = { */ MAP_STYLE_CHANGE: 'map:stylechange', - /** Emitted when the map has fully loaded. */ + /** Emitted once, when the initial base map style has loaded. */ MAP_LOADED: 'map:loaded', /** - * Emitted when the map is ready for interaction and initial app state is settled. + * Emitted when the map instance has been created and initial app state (style and size) is settled. + * The base map style may still be loading; wait for `MAP_LOADED` before adding sources or layers + * to the underlying map. * * Payload: * - `map` — the underlying map instance From 10269e71b522164034e377ecaa568b3eec1befa6 Mon Sep 17 00:00:00 2001 From: Dan Leech Date: Tue, 20 Oct 2026 11:33:29 +0100 Subject: [PATCH 2/2] Clarify map:ready and map:loaded timing across providers --- docs/api.md | 8 ++++---- docs/api/context.md | 2 +- src/config/events.js | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/api.md b/docs/api.md index 04652b56..c422448d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1056,9 +1056,9 @@ interactiveMap.on('app:continue', ({ pluginStates, mapState }) => { ### `map:ready` -Emitted when the underlying map instance has been created and initial app state (style and size) has settled. The map is created once the layout and safe zone have been calculated, so the initial padding, bounds and centre already account for the interface. +Emitted when the underlying map instance has been created and initial app state (style and size) has settled. The map is created once the layout and safe zone have been calculated, and uses the safe zone as its initial padding. -The base map style may still be loading when `map:ready` fires. Wait for [`map:loaded`](#maploaded) before adding sources or layers to the underlying map. +The base map may still be loading when `map:ready` fires. Wait for [`map:loaded`](#maploaded) before adding sources or layers to the underlying map. **Payload:** @@ -1080,9 +1080,9 @@ interactiveMap.on('map:ready', ({ map, mapStyleId, mapSize }) => { ### `map:loaded` -Emitted once, when the initial base map style has loaded. Emitted after `map:ready`. Sources and layers can be added to the underlying map from this point. +Emitted once, when the initial base map has loaded. Emitted after `map:ready`. Sources and layers can be added to the underlying map from this point. -**Payload:** None +**Payload:** None on MapLibre and OpenLayers. ESRI passes the current map state (`center`, `bounds`, `resolution`, `zoom`, `isAtMaxZoom`, `isAtMinZoom`). ```js interactiveMap.on('map:loaded', () => { diff --git a/docs/api/context.md b/docs/api/context.md index fcef4a0f..b2495345 100644 --- a/docs/api/context.md +++ b/docs/api/context.md @@ -96,7 +96,7 @@ Current map state, including: } ``` -`mapState.isMapReady` is `true` once the map instance has been created (`map:ready`). The base map style may still be loading at that point; check `mapProvider.isBaseMapReady()` before adding sources or layers to the underlying map. +`mapState.isMapReady` is `true` once the map instance has been created (`map:ready`). The base map may still be loading at that point; check `mapProvider.isBaseMapReady()` before adding sources or layers to the underlying map. --- diff --git a/src/config/events.js b/src/config/events.js index 6272b4ac..81ebbc0f 100644 --- a/src/config/events.js +++ b/src/config/events.js @@ -178,12 +178,12 @@ export const EVENTS = { */ MAP_STYLE_CHANGE: 'map:stylechange', - /** Emitted once, when the initial base map style has loaded. */ + /** Emitted once, when the initial base map has loaded. */ MAP_LOADED: 'map:loaded', /** * Emitted when the map instance has been created and initial app state (style and size) is settled. - * The base map style may still be loading; wait for `MAP_LOADED` before adding sources or layers + * The base map may still be loading; wait for `MAP_LOADED` before adding sources or layers * to the underlying map. * * Payload: