fix(ios): custom LocationPuck images missing on initial style load by SamuelBrucksch · Pull Request #4291 · rnmapbox/maps

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch · 2026-08-31T05:42:16Z

RNMBXImages is the only style-image producer that doesn't override waitForStyleLoad(), so it registers on subview insert. With an async styleURL that's before the style has loaded, and since RNMBXMapView marks the entry addedToMap, addFeaturesToMap skips it on .styleLoaded — the images never reach the rendered style.

Layers mask this: a missing icon fires the style's image-missing event and addMissingImageToStyle adds it on demand (at the cost of an onImageMissing burst on every load). RNMBXNativeUserLocation can't — _fetchImages reads style.imageExists directly, so _apply() hits .makeDefault() and a LocationPuck with a valid topImage silently renders as the stock blue puck.

Initial load only: applyStyleURL gates refreshComponentsBeforeStyleChange() and the re-add on !initialLoad, so a style switch works. A local styleJSON also masks it, being applied before the components mount.

Waiting is consistent with the rest: RNMBXLayer and RNMBXNativeUserLocation already override to true, and Android registers from Style.OnStyleLoaded (requiresStyleLoad defaults to true there). Nothing can consume style images before the style exists, and addFeaturesToMap preserves subview order, so an <Images> above its consumers is still registered first.

Verified on device (iOS + CarPlay, 10.3.5 / Maps SDK 11.29.0) with a remote styleURL, <Images nativeAssetImages={['car_icon']}> and <LocationPuck topImage="car_icon" />: before, the default puck plus onImageMissing for images that are in nativeAssetImages; after, the custom puck on first load and no missing-image burst.

RNMBXImages did not override waitForStyleLoad, so it was added on subview insert. With an async styleURL that happens before the style has loaded, and because RNMBXMapView marks the feature entry addedToMap, addFeaturesToMap skips it on .styleLoaded - the images never reach the loaded style. Layers mask this via the style's image-missing event, but RNMBXNativeUserLocation reads style.imageExists directly and silently falls back to Puck2DConfiguration.makeDefault().

SamuelBrucksch requested a deployment to CI with Mapbox Tokens August 31, 2026 05:42 — with GitHub Actions Waiting

SamuelBrucksch changed the title ~~fix(ios): register style images after the style has loaded~~fix(ios): custom LocationPuck images missing on initial style loadAug 31, 2026