Mapbox GL JS Updates & Release Notes

Features and improvements ✨

• Improve performance on map views with CJK glyphs by moving CJK rasterization offscreen.
• Improve tile load performance via optimization of style property values recalculation.
• Improve rendering performance via per-frame main thread work optimizations.
• Add support of *-ignore-placement and *-allow-overlap in global placement.

Bug fixes 🐞

• Fix coverage stencil marks including polygons for other road classes, which hid roads that should stay visible.
• Fix imported styles silently rendering nothing when the import fires a non-fatal error while loading.
• Fix raster tiles occasionally showing the image of a different tile after zooming or panning on a slow network.
• Fix building layer filters that use distance, within or worldview dropping buildings.
• Fix a sudden camera jump at the end of long flyTo camera animations.
• Fix 0 fadeDuration symbol placement offset.
• Fix projection documentation incorrectly stating that custom layers are not supported on globe.
• Fix per-feature symbol/line paint value update based on light changes.

Breaking changes ⚠️

Right-to-left text (such as Arabic and Hebrew) is now supported out of the box, loading a small WebAssembly module the first time it appears on the map. setRTLTextPlugin, getRTLTextPluginStatus and the PluginStatus type are removed.

The base size of icons in the text-field property is now calculated at the tile zoom level with the largest text size. As a result, the icons can be smaller when the text size depends on the zoom level.

Features and improvements ✨

• Improve memory use & map load time, especially for 3D layers.
• Improve line rendering performance by using a uniform instead of a shader permutation for line-dasharray.
• Add support for offsetting a control from its corner via map.addControl(control, {position, offset: {x, y}}).
• Improve 3D Lanes map load performance.
• Avoid placing parent-tile symbols when using the global placement.
• Extend global placement debug info.

Bug fixes 🐞

• Fix a severe performance regression when updating data-driven line layers with setPaintProperty.
• Fix a rendering issue when drawing thousands of data-driven lines and symbols.
• Fix transparent building and fill-extrusion layers blending the same pixel twice where they cover the same buildings, making the overlap look more opaque than either layer's opacity asks for.
• Fix an issue with GeoJSON geometries past longitude -+360 or latitude +-85 rendering incorrectly.
• Fix map-aligned icon-rotate and text-rotate not being measured from true north in projections other than Mercator or globe, which misrotated symbols such as crosswalks.
• Fix collision boxes not matching rotated symbols that use appearances with a layout icon-rotate or text-rotate.
• Fix symbol fading not finishing when using global placement.

Features and improvements ✨

• Slightly improve map load time via more aggressive chunk preloading.
• Improve style parsing performance.
• Preload Meshopt decoder earlier to improve 3D styles load time.
• Improve map load time by requesting the icon set earlier and lazy parsing icons on-demand.
• Add support for the globe to mercator transition when using the global placement.
• Add support for symbol fading when using the global placement.
• Add debug visualization support when using the global placement.
• CustomLayerInterface#render/#prerender now receive a CustomLayerRenderParameters object as an 8th argument, exposing projectionMatrix (camera→clip), viewMatrix (world→camera) pair, plus the globe horizon globeClippingPlane and the globe center's screen position globeCenterInScreenPixels.

Bug fixes 🐞

• Fix raster-array chunk loading when unused.
• Fix transformRequest headers and credentials being dropped from PMTiles requests.
• Fix transformRequest headers/credentials being dropped when loading GL model (GLTF) resources.
• Fix features rendering at the wrong position when a layer uses a within filter and the map uses a projection other than Mercator or globe.
• Fix global placement throwing an error when placing symbols with no text.
• Fix setting padding as a sideeffect in a preloadOnly animation.

Breaking changes ⚠️

Make pitch and rotation states independent. Previously, disabling rotation also disabled pitch. Now, pitch can be enabled independently of rotation.

Features and improvements ✨

Extract the terrain from the core ESM module.

Reduce shader size by removing unused code paths.

Upgrade Supercluster to v9 (optimize clustering memory footprint).

Add support for client-side overzooming for raster-array sources.

Add AnimationFrameProvider (MapOptions.animationFrameProvider) to support driving the render loop from an external library.

Enable landmark model LOD mesh download when the server provides such data.

Raise the maximum number of sources in a style to 64.

Bug fixes 🐞

Fix dark line artifacts on non-standard procedural building geometry.

Fix ESM terrain module loading for elevated-lines requiring terrain.

Fix validation of style light transition properties.

Fix symbol layer related errors after GL context loss.

Skip rings with zero area on fill-extrusions.

Breaking changes ⚠️

Remove legacy undocumented Map addSourceType API which was superceded by CustomSourceInterface and experimental TileProvider API.

Features and improvements ✨

Add new raster-color-scale property, which can be set to "log" to improve color ramp precision when visualizing long-tailed raster datasets.

Add new raster-allow-draping property that can be set to false to disable raster layer draping over globe/terrain.

Move symbol-z-offset property out of experimental.

Extend distance expression to accept an expression as a second argument.

Extend config expression to support object literals as values.

Improve dashed line rendering in pitched views.

Added APIs for more granular control of interaction handlers:
map.keyboard: disablePitch, enablePitch, isPitchEnabled, disableBearing, enableBearing, isBearingEnabled, isEnabled
map.dragRotate: disableRotation, enableRotation, isRotationEnabled
map.touchZoomRotate: isRotationEnabled, isTapDragZoomEnabled
For all three, isEnabled is changed from AND to OR semantics

Bug fixes 🐞

Fix rare line artifacts on sharp corners with short segments and non-bevel joins.

Fix ambient occlusion to not render for elevated (non-zero-base) extrusions.

Fix Map resetFeatureStates not working properly in some scoped styles.

Breaking changes ⚠️

Disable text-variable-anchor when appearances are present.

Features and improvements ✨

Introduce experimental map.getVerticalFieldOfView(), map.setVerticalFieldOfView(), and read-only map.getHorizontalFieldOfView() and an animatable fov camera option.

Expose line-border-width and line-border-color as public paint properties.

Introduce experimental line-border-gradient property for rendering gradient borders on lines.

Add support for Meshopt v1 compressed models.

Support string color values for the model-color in a model source.

Add map.resetFeatureStates() to clear all feature states for a featureset or layer.

Expose map.getSchema()/map.setSchema() for managing the imported style's schema.

Extract development and debug code from the ESM bundle into a separate module.

Extract more model code from the ESM core bundle.

Extract raster-array layer as a separate ESM module.

Reduce the bundle size by restructuring style, program, symbol, and expression code.

Remove experimental flag from layer appearances.

Improve symbol layer performance.

Reduce redundant repaints and checks during initial load.

Bug fixes 🐞

Fix double rotation of the FF5C character in vertical text rendering.

Preserve live gesture when camera setter is called from inside a drag/move handler.

Stop overwriting the pointerEvents of markers set by the user.

Fix models with vertex alpha 0 appearing black.

Fix incorrect rendering of fill extrusions with fill-extrusion-edge-radius at low zoom levels in some cases.

Features and improvements ✨

• Upgrade to Typescript 7
• Add cross-source HD roads elevation for symbols
• Improve character rotation logic for some CJK characters in vertical text rendering mode

Bug fixes 🐞

• Fix raster-array out of bounds assertion error for non-mecator projections
• Fix error when object-property strings were used in expressions
• Fix wrong access token used on multi-map environments
• Fix number-format dropping min/max-fraction-digits when they were 0
• Fix line-aligned label placement during globe-mercator transition
• Fix crash when using style expressions with prototype-derived keys
• Fix atlas cache returning another scope images
• Fix Style#{get,set,remove}FeatureState with {target: {layerId}} so imported-layer targets resolve against their own fragment's sources instead of the root style's
• Fix missing building along tile borders
• Fix dynamic imports in UMD
• Fix import.meta crash under modern bundlers
• Fix setPaintProperty on symbol properties with a transition duration of 0

Breaking changes ⚠️

Remove transition and interpolated flags from the camera-projection style property — enum properties cannot be transitioned, so these flags were incorrect.

Features and improvements ✨

Make published TypeScript declarations self-contained, fixing consumer builds that failed with skipLibCheck: false.

Improve terrain raycast accuracy for mouse events, camera fitting, and other pointer interactions.

Improve landmark model LOD switching with size-based distance heuristics for better rendering performance.

Bug fixes 🐞

Fix hd-road-markup elevated lines rendering flat with zero-exaggeration terrain.

Fix viewport-y symbol sorting causing a Vertex buffer is not big enough for the draw call error when a symbol bucket had multiple segments.

Fix multilinestrings not displaying labels correctly.

Fix parametric colors sometimes loading the wrong cached image.

Breaking changes ⚠️

Switch the ESM entry point to named exports (import * as mapboxgl from 'mapbox-gl/esm') so that modern bundlers can eliminate small unused parts of the code. Replace mapboxgl.accessToken with Map accessToken option. Most of the bundle still can't be statically eliminated, but this release also improves lazy loading of code at runtime, with more improvements on the way.

Features and improvements ✨

Extend Map getLayerProperty and setLayerProperty to support layer-level properties (minzoom, maxzoom, filter, slot, appearances)

Extend TileProvider API to accept ImageBitmap for raster and raster-dem providers.

Improve model loading and rendering performance.

Improve symbol rendering performance.

Improve performance of decoding and encoding vector tiles and other protobuf-encoded assets.

Improve color parsing performance, slightly improving load time for styles with many color values.

Extract indoor and part of the model rendering code to be loaded on demand when using the ESM entry point.

Add GeolocateControl ready event and setShowAccuracyCircle, setShowUserHeading, setFitBoundsOptions, setShowUserLocation methods.

Add KeyboardHandler disablePan/enablePan methods.

Add DragRotateHandler disablePitch/enablePitch methods.

Add TouchZoomRotateHandler disableTapDragZoom/enableTapDragZoom methods.

Expose Map setLanguage, getLanguage, setWorldview, getWorldview as stable public methods (previously private).

Remove all direct dependencies from package.json slightly improving NPM install size and time.

Improve anti-aliasing for lines with borders.

Implement automatic conflation of regular and HD road data in preparation for future Mapbox Standard updates.

Bug fixes 🐞

Fix an issue that sometimes caused black boxes to appear instead of symbol icons.

Fix precision issues on tile borders for elevated roads.

Fix rendering issues for stacked underground roads.

Fix minor vulnerabilities related to Object prototype pollution from an untrusted style or tiles.

Fix the Cutoff is currently disabled on terrain warning on Standard style.

Fix appearance conditions validation to accept compound expressions.

Fix issues with model cutout fading via model-line-cutout-mode property.

Fix an issue with step expression evaluation for symbol layers.

Fix an issue with custom layer rendering alongside data-driven line-emissive-strength

Features and improvements ✨

Introduce Level of Detail (LOD) support for landmark models, enabling automatic switching between model versions based on camera distance.

Support additive blend mode with clamped density by setting the line-blend-additive-clamp property.

Improve rendering performance by reducing per-frame matrix allocations.

Improve rendering performance via parallel shader compilation on supported devices.

Improve rendering performance by advancing shader precompilation.

Improve shadow rendering performance.

Improve vector icon loading performance.

Improve initial load by skipping redundant config-related style layers updates in Web Workers.

Improve initial load by rescheduling shader precompilation to occur during browser idle time after the map's idle event.

Improve model processing performance.

Improve performance and memory footprint by streamlining communication between the main thread and Web Workers.

Reduce first-interaction jank by optimizing shader compilation pipeline behavior.

Optimize expression parsing performance.

Improve an error messaging for the line-trim-offset property without lineMetrics.

Bug fixes 🐞

Fix LUT to properly work with premultiplied color.

Fix a potential memory leak and crash occurring when a map was destroyed.

Fix an issue where cross-fragments config values were not correctly updated.