MapLibre GL JS

✨ Features and improvements

• Make fired/listened map events typed. This means that map.on("something", ...) (and once, listens) will now give you an typescript error and better autocomplete. If you relied on firing/listening custom events via the map, this still works via the escape hatches map.fire("something" as any) -> map.on("something" as any, ...) (#8072) (by @CommanderStorm)
• Let a StyleImageInterface give a {renderWithWebGL} callback as its data, an escape hatch for plugin developers and advanced users that renders a style image on the GPU instead of moving its pixels through the CPU. Nothing new is possible that pixels could not already express, but an image that changes often, such as an animated icon, gets more performant (#7954) (by @lucaswoj)
• Use integer vertex attributes for packed line data instead of float conversion (#7640) (by @johncarmack1984)
• Use integer vertex attributes for packed circle, heatmap, symbol, and fill-extrusion data instead of float conversion (#7640, #8143) (by @johncarmack1984)
• Redesign benchmarks to use vitest bench capabilities and remove custom build for benchmarks code (#982) (by @johncarmack1984)

🐞 Bug fixes

• Fix terrain pan/zoom gestures losing the grabbed terrain point: gestures are now solved against the elevation of the terrain under the gesture instead of the frozen center elevation, so terrain under the pointer/fingers no longer slips during moving-centroid pinches and drags (#8067) (by @StrawberryJam22)
• Fix ImageSource, VideoSource and CanvasSource leaking a GPU texture on every image update and on removal, and a resized texture losing its wrap and filter settings (#8094) (by @mondsichtung)
• Fix map.queryRenderedFeatures() sometimes causing "Out of bounds" error due to race condition while loading tile data (#8064) (by @smvjohansenbouvet)
• Fix zooming the globe with the scroll wheel or a two-finger pinch drifting away from the pointer while the globe is small on screen, instead of keeping the location under the pointer as it does when zoomed in (#8095) (by @mondsichtung)
• Fix projective rendering for non-parallelogram image source quads (#7887) (by @i4innovationnet)

✨ Features and improvements

• Add the fill-extrusion-rounded-corner-distance layout property, which replaces each fill-extrusion corner with an arc spanning the given distance (in meters) along the adjacent edges. The distance is clamped to 20% of each adjacent edge's length so that short edges don't collapse, and near-straight corners (turns below 5°) are left untouched. Defaults to 0, which keeps corners sharp (#7934) (by @CommanderStorm)
• Improve Mercator rendering performance by skipping a redundant clipping mask border pass (#8038) (by @DoFabien)
• Add a docker-compose service to build and serve the examples (#57) (#8026) (by @clement-igonet)

🐞 Bug fixes

• Fix rare rendering bug causing two adjacent layers with different data driven property set to render wrong (#8068) (by @CommanderStorm)
• Improve terrain elevation sampling performance by caching DEM tile lookups and coordinate transforms within each render (#8025) (by @DoFabien)

✨ Features and improvements

• Add support for updating an ImageSource with an already-decoded image (HTMLImageElement, HTMLCanvasElement, ImageBitmap or ImageData) directly via ImageSource.updateImage({image}), skipping the network request (#7944) (by @mondsichtung)
• Add GeoJSONSource.getClusterOptions to get a source's current cluster options (cluster, clusterMaxZoom, clusterRadius) (#7948) (by @lazerg)
• Support global-state expressions in sky.*, light.* and projection.type properties (#7966, #7967, #7968) (by @CommanderStorm)
• Add MapOptions.rotateSpeed and MapOptions.pitchSpeed, the degrees the bearing/pitch change per pixel dragged (#7949) (by @clement-igonet)
• Show a grab cursor over draggable markers, including on non-interactive maps (#8019) (by @hugosmoreira)

🐞 Bug fixes

• Use role=img for non-interactive default markers and role=button when they become interactive (#7790) (by @cat0825)
• Fix an error thrown when a paint property transitions between arrays of different length (#6606) (by @HarelM)
• Fix renderer crash when RasterTileSource.setTiles/setUrl is called while the source contains errored tiles (#7911) (by @lazerg)
• Fix 3D buildings disappearing when the camera pitches up to look near the horizon, by growing tile-culling bounds as the frustum's bottom edge (from pitch and FOV) approaches horizontal (#7633) (by @clement-igonet)
• Fix globe latitude precision on some GPUs (e.g. Mali) by reformulating the mercator-to-sphere Y coordinate algebraically (exp + rational arithmetic instead of atan/sin/cos), avoiding float32 cancellation and imprecise hardware transcendentals near the equator; the runtime GPU atan-error measurement/correction this superseded has also been removed (#7419) (by @clement-igonet)
• Fix a race in RasterTileSource.loadTile and ImageSource.load where a tile/image aborted during an awaited transformRequest passed an undefined AbortController into the image request queue, crashing it with TypeError: Cannot read properties of undefined (reading 'signal') (#8004) (by @jan-grzybek)
• Fix setTerrain not destroying the previously active terrain when switching to a new configuration, which leaked its GPU resources and left the old source still configured as a terrain source (#7990) (by @lazerg)
• Fix fill and line layers being rendered twice near the antimeridian on globe when looking at poles or when zoomed out (#6248) (by @pabueco)

The following incorporates all the pre-releases for version 6 changes. Check-out our migration guide from v5 to v6 for more information.

✨ Features and improvements

• ⚠️ Switch to an ESM-only distribution (maplibre-gl.mjs). The UMD bundles (maplibre-gl.js, maplibre-gl-csp.js) are no longer published. The CSP-specific bundle is also dropped: the ESM build loads its worker as a real URL, so worker-src blob: is no longer required. Consumers using <script src=".../maplibre-gl.js"> must switch to <script type="module">, and consumers using import maplibregl from 'maplibre-gl' must switch to import * as maplibregl from 'maplibre-gl' or named imports. See the docs ESM section or our migration guide for migration steps. (#6254) (by @birkskyum)
• ⚠️ Interpolate the light position in spherical coordinates instead of cartesian ones, so that a transition keeps its radial distance. (#7919) (by @HarelM)
• ⚠️ styleimagemissing is now a notify-only event instead of the previous callback that allowed to provide an image. This aligns the event with standard event semantics (notify, not resolve). Use Map.setMissingStyleImageResolver to on-demand supply images instead via an function that can now also be async. (#7892) (by @birkskyum)
• ⚠️ Map now composes a Camera instead of extending it (Map extends Evented directly and forwards the camera API). The internal map.transform was removed — use map's public API instead or open a PR if you need something that's not exposed. Removed the internal transform.getMatrixForModel helper (#7800) (by @HarelM)
• ⚠️ All map events are now real classes that are instantiated when they are fired. Renamed the Maps' BoxZoom handler from MapLibreZoomEvent to MapBoxZoomEvent, added the rollstart/roll/rollend and style.load (as MapStyleLoadEvent) events to MapEventType, and added event classes and type-map for Marker, Popup, GeolocateControl and FullscreenControl. Removed MapDataEvent: the data/dataloading/dataabort events are now MapSourceDataEvent | MapStyleDataEvent, so source data events carry the full source info (sourceId, tile, sourceDataType, …). Added MapMovementEvent as the type for all camera-transition events (move/zoom/rotate/pitch/roll/drag and their start/end variants). Evented is now generic over an event-type map (Evented<EventType>) and is abstract, so subclasses get strongly-typed on/once/off automatically without re-declaring overloads — this also types the events on Camera/Style (via MapEventType) and on the sources (via the new SourceEventType) (#7789) (by @HarelM)
• ⚠️ Update maplibre-gl-style-spec to version 25, which now throws an error with warning severity instead of silently failing on encoutering legacy expressions (#7792) (by @HarelM)
• ⚠️ Removed the remaining mapbox references in the code and in the tests. This changes the #pragma mapbox to #pragma maplibre in case you have shader code that relied on it. (#7761) (by @HarelM)
• ⚠️ zoomLevelsToOverscale default value was changed to 4 to support better handling of high level zoom with dense labels. This might have a side effect of changing a bit the results of queryRenderedFeatures and some rendering of polygon center label. To revert this change, set the value to undefined (#7537) (by @HarelM)
• ⚠️ Remove the second parameter from GeoJSONSource.setData (waitForCompletion) and remove the return value of this to allow future changes to the API (#7538) (by @HarelM)
• ⚠️ The TypeScript target has been updated to ES2022. This results in smaller bundles and improved runtime performance by relying on modern JavaScript features and reducing transpilation. Consumers targeting browsers or using some tooling released before 2022 may need to transpile MapLibre or update. This change also aligns all internal build configurations to a single target instead of ES2016 + ES2019, avoiding inconsistencies in emitted code. (#7404) (by @CommanderStorm)
• ⚠️ WebGL (v1) support has been removed; WebGL2 is now required. In practical terms, this will not change how you interact with the map. This enables performance improvements (e.g. line opacity), Terrain3D enhancements, and several bug fixes. WebGL2 support has been widely available for years, and usage of the legacy path had plateaued, so maintaining it no longer justified the added complexity. To ease this breaking change, we have also refactored how we handle the case that no webgl is avaliable (e.g. due to browser restrictions). You can now listen to the webgl error via .on("error"). See caniuse.com/webgl2 for ecosystem support and our RFC for details. (#7453) (by @CommanderStorm)
• ⚠️ Support geojson nested objects, this is a breaking change as it encodes __$json__ before properties that used to be an object. It also parses them back, but this is still a breaking change if you assumed this bug existed. (#6992) (by HarelM)
• ⚠️ Improve types for {get,set}LayoutProperty, {get,set}PaintProperty to be the actual type instead of string/any (#7481) (by @CommanderStorm)
• ⚠️ Refactored the Hash-based location control (the option that syncs map state to the URL like #map=5/1/2) to use URLSearchParams internally. This improves extensibility for custom use cases, but may break existing code that relies on the previous implementation. It also changes how certain edge cases are parsed—for example, strings like #10%2F3.00%2F-1.00 are now accepted, and hashes like #foo are normalized to #foo=. (#7073) (by @CommanderStorm)
• Validate the terrain passed to map.setTerrain, which was previously applied unchecked (#7941) (by @HarelM)
• Improve runtime error warnings to point at the offending style location (e.g. layers[3].paint.line-color, layers[3].filter) instead of just logging the bare error message (#7869) (by @CommanderStorm)
• Improve terrain render-to-texture preparation performance by skipping sources that are not rendered to terrain textures (#7863) (by @DoFabien)
• Add Map.setMissingStyleImageResolver for resolving missing style images with sync or async callbacks (#7850) (by @birkskyum)
• Add RasterTileSource#setPremultiplyAlpha(false) to preserve raw RGBA tile values when alpha is used for data instead of opacity (#7235) (by @plantain).
• Drop the archived @mapbox/whoots-js dependency by inlining its single getTileBBox helper (#7838) (by @qorexdevs)
• Debounce setImages broadcast to once per animation frame, fixing O(n²) serialization overhead when adding many images (#7614) (by @bradymadden97)
• Improve terrain rendering performance by avoiding unnecessary terrain data lookups during Mercator render-to-texture passes (#7833) (by @DoFabien)
• Reduce allocation pressure while constructing DEM data and sampling terrain elevations (#7814) (by @DoFabien)
• Reuse terrain DEM texture when preparing terrain (#7813) (by @DoFabien)
• Add fill-layer-opacity and line-layer-opacity paint properties, which apply opacity to the entire layer output uniformly (#7570) (by @CommanderStorm)
• Build main and worker in same build context to extract shared chunk (#7745) (by @dangkyokhoang)
• Revert the line-opacity-driven offscreen rendering introduced in #7490 (#7764) (by @CommanderStorm). The overlap-artefact fix is now driven by line-layer-opacity instead.
• Improve ProjectionData matrix backing types for renderer and custom layer projection matrices (#6316) (by @cat0825)
• Optimization: vertex shader opacity culling for lines and fills #7711 (by @xavierjs)
• Use a shared FBO for the terrain cache render to texture #7637 (by @xavierjs)
• Use flat to opt out of interpolation for constant shader varyings (#7661) (by @birkskyum)
• Replace texImage2D with texStorage2D for immutable textures (#7643) (by @birkskyum)
• Enable mipmaps for non-power-of-two raster tiles, reducing aliasing at high pitch (#7641) (by @birkskyum)
• Use GLSL ES 3.00 layout qualifiers for vertex attribute locations, replacing runtime bindAttribLocation calls (#7644) (by @birkskyum)
• Adopt isolatedDeclarations and switch dts emitter from tsgo to oxc (#7566) (by @birkskyum)
• Improve 3D terrain performance (#7549) (by @lucaswoj)
• Replace dts-bundle-generator with rolldown-plugin-dts for 78.2x faster .d.ts generation. (#7564) (by @birkskyum)
• Replace ts-node with Node 24's native TypeScript support for build scripts. (#7565) (by @birkskyum)
• Bump typescript to v7 beta - 3.5x faster typecheck (#7556) (by @birkskyum)
• Add a new map creation option, terrainSkirtLength, which allows the removal of visually unappealing vertical artifacts when using a terrain along with a transparent background (#7523) (by @safwat-halaby)
• Bundle with Rolldown instead of Rollup (#7555) (by @birkskyum)
• Optimization for Feature State: Replace String-Indexed Object with Array (up to 3.4X speedup) (#7550) (by @xavierjs)
• Expose getProjectionData function in custom layer args objects (#7471) (by @kubapelc)
• Marked package sideEffects as CSS-only in package metadata, which may improve tree-shaking and reduce bundle size in some bundlers (#7258) (by @CommanderStorm)

🐞 Bug fixes

• ⚠️ Fix transparent, overlapping lines creating artefacts. This is fixed for line-opacity, but purposefully not for transparent line-color properties, thus still allowing transparent colors to stack their effect. (#7490) (by @CommanderStorm)
• ⚠️ Disable icon scaling with offset, this is a render breaking change which we have decided to incorporate in both maplibre-gl-js and maplibre-native (#7742) (by @springmeyer and @HarelM)
• Log style validation warnings instead of treating them as errors, so that a filter mixing legacy and expression syntax no longer aborts the style load and blanks the map (#7941) (by @HarelM)
• Validate raster-dem sources passed to map.addSource, which were previously skipped. Stop a source type the style spec has no schema for, such as one registered with addSourceType, from failing the whole style. Previously only canvas was let through (#7941) (by @HarelM)
• Fix line-layer-opacity/fill-layer-opacity clipping away a subsequent layer that shares the same source (#7867) (by @CommanderStorm)
• Fix camera jump in flyTo when minZoom is set (#7743) (by @YuChunTsao)
• Fix stale terrain depth and coordinate framebuffers when terrain tiles change without camera movement (#7812) (by @DoFabien)
• Fix a memory leak where aborting a worker request (e.g. a GeoJSON tile load cancelled while panning) left its promise pending forever, so the awaiting async frame and everything it captured was never released; Actor.sendAsync now rejects with an AbortError on abort (#7826) (by @kamil-sienkiewicz-asi)
• Skip undefined properties during worker serialization (#7801) (by @xavierjs)
• Fix cross-origin module worker loading to preserve ESM semantics (#7796) (by @dangkyokhoang)
• Fix conflicting reloads of tiles causing an error in queryRenderedFeatures (#7765) (by @ckolin)
• Fix a race condition in geojson source after init and fast update data (#7734) (by @HarelM)
• Fix camera jump on dragend with globe + terrain at low pitch (#7736) (by @kodeezabdullah)
• Fix web font rendering by awaiting document.fonts.load() before TinySDF instantiation (#7735) (by @kodeezabdullah)
• Remove the framebuffer completeness check that threw an unhandled Framebuffer is not complete error on transient GPU resource loss (e.g. when a tab wakes from sleep); incomplete framebuffers now self-heal on the next frame instead (#7303) (by @johanrd)
• Fix handling cross-origin blob URL in Ajax utils (#7675) (by @katemihalikova)
• Avoid TypeErrors from style methods while the WebGL context is lost (#7710) (by @cyphercodes)
• querySourceFeatures() throws 'Block overruns tile' on overzoomed MLT tiles because the reported encoding doesn't match the re-encoded MVT data (#7707) (by @ted-piotrowski)
• Fix geometry length check for polygons and lines in LineBucket after duplicate vertex trimming(#7638) (by @widefire)
• line-dasharray step transition lags one zoom level when the step's branches are data-driven (#7705) (by @lucaswoj)
• Fix feature state bulk remove + feature set per-id set does not remove state of first feature (#7554) (by @xavierjs)
• Remove error when actor doesn't have a registered message type for better usability of custom messages in workers (#7589) (by @HarelM)
• Auto-load worker module for CDN usage (#7595) (by @birkskyum)
• Fix Large number of feature state keys leads to zoom lag when loading cached tiles (#7590) (by @xavierjs)
• Fix issue when map's max zoom and source max zoom are close to eachother (#7567) (by @HarelM)

✨ Features and improvements

• Validate the terrain passed to map.setTerrain, which was previously applied unchecked (#7941) (by @HarelM)
• Improve runtime error warnings to point at the offending style location (e.g. layers[3].paint.line-color, layers[3].filter) instead of just logging the bare error message (#7869) (by @CommanderStorm)
• ⚠️ Interpolate the light position in spherical coordinates instead of cartesian ones, so that a transition keeps its radial distance. (#7919) (by @HarelM)

🐞 Bug fixes

• Log style validation warnings instead of treating them as errors, so that a filter mixing legacy and expression syntax no longer aborts the style load and blanks the map (#7941) (by @HarelM)
• Validate raster-dem sources passed to map.addSource, which were previously skipped. Stop a source type the style spec has no schema for, such as one registered with addSourceType, from failing the whole style. Previously only canvas was let through (#7941) (by @HarelM)

✨ Features and improvements

• Improve terrain render-to-texture preparation performance by skipping sources that are not rendered to terrain textures (#7863) (by @DoFabien)
• Add Map.setMissingStyleImageResolver for resolving missing style images with sync or async callbacks (#7850) (by @birkskyum)
• ⚠️ Stop allowing styleimagemissing listeners to resolve the current image request; use Map.setMissingStyleImageResolver instead (#7892) (by @birkskyum)
• Add RasterTileSource#setPremultiplyAlpha(false) to preserve raw RGBA tile values when alpha is used for data instead of opacity (#7235) (by @plantain).

✨ Features and improvements

• ⚠️ Map now composes a Camera instead of extending it (Map extends Evented directly and forwards the camera API). The internal map.transform was removed — use map's public API instead or open a PR if you need something that's not exposed. Removed the internal transform.getMatrixForModel helper (#7800) (by @HarelM)

🐞 Bug fixes

• Fix line-layer-opacity/fill-layer-opacity clipping away a subsequent layer that shares the same source (#7867) (by @CommanderStorm)
• Fix camera jump in flyTo when minZoom is set (#7743) (by @YuChunTsao)

✨ Features and improvements

• Drop the archived @mapbox/whoots-js dependency by inlining its single getTileBBox helper (#7838) (by @qorexdevs)
• Debounce setImages broadcast to once per animation frame, fixing O(n²) serialization overhead when adding many images (#7614) (by @bradymadden97)

🐞 Bug fixes

• Fix stale terrain depth and coordinate framebuffers when terrain tiles change without camera movement (#7812) (by @DoFabien)

✨ Features and improvements

• Improve terrain rendering performance by avoiding unnecessary terrain data lookups during Mercator render-to-texture passes (#7833) (by @DoFabien)
• Reduce allocation pressure while constructing DEM data and sampling terrain elevations (#7814) (by @DoFabien)
• Reuse terrain DEM texture when preparing terrain (#7813) (by @DoFabien)

🐞 Bug fixes

• Fix a memory leak where aborting a worker request (e.g. a GeoJSON tile load cancelled while panning) left its promise pending forever, so the awaiting async frame and everything it captured was never released; Actor.sendAsync now rejects with an AbortError on abort (#7826) (by @kamil-sienkiewicz-asi)

✨ Features and improvements

• ⚠️ All map events are now real classes that are instantiated when they are fired. Renamed MapLibreZoomEvent to MapBoxZoomEvent, added the rollstart/roll/rollend and style.load (as MapStyleLoadEvent) events to MapEventType, and added event classes and type-map for Marker, Popup, GeolocateControl and FullscreenControl. Removed MapDataEvent: the data/dataloading/dataabort events are now MapSourceDataEvent | MapStyleDataEvent, so source data events carry the full source info (sourceId, tile, sourceDataType, …). Added MapMovementEvent as the type for all camera-transition events (move/zoom/rotate/pitch/roll/drag and their start/end variants). Evented is now generic over an event-type map (Evented<EventType>) and is abstract, so subclasses get strongly-typed on/once/off automatically without re-declaring overloads — this also types the events on Camera/Style (via MapEventType) and on the sources (via the new SourceEventType) (#7789) (by @HarelM)

🐞 Bug fixes

• Skip undefined properties during worker serialization (#7801) (by @xavierjs)

✨ Features and improvements

• ⚠️ Update maplibre-gl-style-spec to version 25, which has a breaking change in legacy expression validation (#7792) (by @HarelM)

🐞 Bug fixes

• Fix cross-origin module worker loading to preserve ESM semantics (#7796) (by @dangkyokhoang)