NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #4928 most downloaded on npm
A WebGL interactive maps library
Last release 5 days ago
29 Sep 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
4 versions withdrawn
withdrawn after publishing
12 years old
299 releases · first in 2014
Slightly improve map load time via more aggressive chunk preloading.
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.raster-array chunk loading when unused.transformRequest headers and credentials being dropped from PMTiles requests.transformRequest headers/credentials being dropped when loading GL model (GLTF) resources.within filter and the map uses a projection other than Mercator or globe.padding as a sideeffect in a preloadOnly animation.extra_bounds on all TileJSON source types.map.remove() where it could retain the map instance in memory.One column per quarter.
Slightly improve map load time via more aggressive chunk preloading.
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.raster-array chunk loading when unused.transformRequest headers and credentials being dropped from PMTiles requests.transformRequest headers/credentials being dropped when loading GL model (GLTF) resources.within filter and the map uses a projection other than Mercator or globe.padding as a sideeffect in a preloadOnly animation.Significantly improve GeoJSON memory footprint.
raster-allow-draping.removeSource throwing under globe projection. (h/t @mhayk)Significantly improve GeoJSON memory footprint.
raster-allow-draping.removeSource throwing under globe projection. (h/t @mhayk)raster-allow-draping.transformRequest headers/credentials being dropped when loading GL model (GLTF) resources.removeSource throwing under globe projection. (h/t @mhayk)Make pitch and rotation states independent. Previously, disabling rotation also disabled pitch. Now, pitch can be enabled independently of rotation.
AnimationFrameProvider (MapOptions.animationFrameProvider) to support driving the render loop from an external library.Make pitch and rotation states independent. Previously, disabling rotation also disabled pitch. Now, pitch can be enabled independently of rotation.
AnimationFrameProvider (MapOptions.animationFrameProvider) to support driving the render loop from an external library.Nothing published for this version
Remove legacy undocumented Map addSourceType API which was superceded by CustomSourceInterface and experimental TileProvider API.
Map addSourceType API which was superceded by CustomSourceInterface and experimental TileProvider API.raster-color-scale property, which can be set to "log" to improve color ramp precision when visualizing long-tailed raster datasets.raster-allow-draping property that can be set to false to disable raster layer draping over globe/terrain.symbol-z-offset property out of experimental.distance expression to accept an expression as a second argument.config expression to support object literals as values.map.keyboard: disablePitch, enablePitch, isPitchEnabled, disableBearing, enableBearing, isBearingEnabled, isEnabledmap.dragRotate: disableRotation, enableRotation, isRotationEnabledmap.touchZoomRotate: isRotationEnabled, isTapDragZoomEnabledisEnabled is changed from AND to OR semanticsMap resetFeatureStates not working properly in some scoped styles.Remove legacy undocumented Map addSourceType API which was superceded by CustomSourceInterface .
Map addSourceType API which was superceded by CustomSourceInterface.raster-color-scale property, which can be set to "log" to improve color ramp precision when visualizing long-tailed raster datasets.raster-allow-draping property that can be set to false to disable raster layer draping over globe/terrain.symbol-z-offset property out of experimental.distance expression to accept an expression as a second argument.config expression to support object literals as values.map.keyboard: disablePitch, enablePitch, isPitchEnabled, disableBearing, enableBearing, isBearingEnabled, isEnabledmap.dragRotate: disableRotation, enableRotation, isRotationEnabledmap.touchZoomRotate: isRotationEnabled, isTapDragZoomEnabledisEnabled is changed from AND to OR semanticsMap resetFeatureStates not working properly in some scoped styles.Fix iconsets icons rendering with ESM bundle.
iconsets icons rendering with ESM bundle.Disable text-variable-anchor when appearances are present.
text-variable-anchor when appearances are present.map.getVerticalFieldOfView(), map.setVerticalFieldOfView(), and read-only map.getHorizontalFieldOfView() and an animatable fov camera option.line-border-width and line-border-color as public paint properties.line-border-gradient property for rendering gradient borders on lines.model-color in a model source.map.resetFeatureStates() to clear all feature states for a featureset or layer.map.getSchema()/map.setSchema() for managing the imported style's schema.raster-array layer as a separate ESM module.pointerEvents of markers set by the user.fill-extrusion-edge-radius at low zoom levels in some cases.Disable text-variable-anchor when appearances are present.
text-variable-anchor when appearances are present.map.getVerticalFieldOfView(), map.setVerticalFieldOfView(), and read-only map.getHorizontalFieldOfView() and an animatable fov camera option.line-border-width and line-border-color as public paint properties.line-border-gradient property for rendering gradient borders on lines.model-color in a model source.map.resetFeatureStates() to clear all feature states for a featureset or layer.map.getSchema()/map.setSchema() for managing the imported style's schema.raster-array layer as a separate ESM module.pointerEvents of markers set by the user.fill-extrusion-edge-radius at low zoom levels in some cases.Nothing published for this version
Add cross-source HD roads elevation for symbols
number-format dropping min/max-fraction-digits when they were 0Style#{get,set,remove}FeatureState with {target: {layerId}} so imported-layer targets resolve against their own fragment's sources instead of the root style'ssetPaintProperty on symbol properties with a transition duration of 0Add cross-source HD roads elevation for symbols
number-format dropping min/max-fraction-digits when they were 0Style#{get,set,remove}FeatureState with {target: {layerId}} so imported-layer targets resolve against their own fragment's sources instead of the root style'sRemove transition and interpolated flags from the camera-projection style property — enum properties cannot be transitioned, so these flags were incor
transition and interpolated flags from the camera-projection style property — enum properties cannot be transitioned, so these flags were incorrect.skipLibCheck: false.hd-road-markup elevated lines rendering flat with zero-exaggeration terrain.viewport-y symbol sorting causing a Vertex buffer is not big enough for the draw call error when a symbol bucket had multiple segments.Remove transition and interpolated flags from the camera-projection style property — enum properties cannot be transitioned, so these flags were incor
transition and interpolated flags from the camera-projection style property — enum properties cannot be transitioned, so these flags were incorrect.skipLibCheck: false.hd-road-markup elevated lines rendering flat with zero-exaggeration terrain.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 minor vulnerabilities related to Object prototype pollution from an untrusted style or tiles.
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.Map getLayerProperty and setLayerProperty to support layer-level properties (minzoom, maxzoom, filter, slot, appearances)TileProvider API to accept ImageBitmap for raster and raster-dem providers.GeolocateControl ready event and setShowAccuracyCircle, setShowUserHeading, setFitBoundsOptions, setShowUserLocation methods.KeyboardHandler disablePan/enablePan methods.DragRotateHandler disablePitch/enablePitch methods.TouchZoomRotateHandler disableTapDragZoom/enableTapDragZoom methods.Map setLanguage, getLanguage, setWorldview, getWorldview as stable public methods (previously private).package.json slightly improving NPM install size and time.Cutoff is currently disabled on terrain warning on Standard style.model-line-cutout-mode property.line-emissive-strengthFix minor vulnerabilities related to Object prototype pollution from an untrusted style or tiles.
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.Map getLayerProperty and setLayerProperty to support layer-level properties (minzoom, maxzoom, filter, slot, appearances)TileProvider API to accept ImageBitmap for raster and raster-dem providers.GeolocateControl ready event and setShowAccuracyCircle, setShowUserHeading, setFitBoundsOptions, setShowUserLocation methods.KeyboardHandler disablePan/enablePan methods.DragRotateHandler disablePitch/enablePitch methods.TouchZoomRotateHandler disableTapDragZoom/enableTapDragZoom methods.Map setLanguage, getLanguage, setWorldview, getWorldview as stable public methods (previously private).package.json slightly improving NPM install size and time.Cutoff is currently disabled on terrain warning on Standard style.model-line-cutout-mode property.line-emissive-strengthFix an issue with custom layer rendering alongside data-driven line-emissive-strength.
line-emissive-strength.Introduce Level of Detail (LOD) support for landmark models, enabling automatic switching between model versions based on camera distance.
line-blend-additive-clamp property.idle event.line-trim-offset property without lineMetrics.Introduce Level of Detail (LOD) support for landmark models, enabling automatic switching between model versions based on camera distance.
line-blend-additive-clamp property.idle event.line-trim-offset property without lineMetrics.Fix a rendering error occurring with fill-extrusion layers when terrain is enabled in specific edge cases.
fill-extrusion layers when terrain is enabled in specific edge cases.Improve the performance of symbol layers on old devices.
TileProvider for raster and raster-dem sources, adding support for PMTiles with raster tiles.import mapboxgl from 'mapbox-gl/esm').line-dasharray not working.scale-factor being applied twice to icons with feature-dependent icon-size.Fix hillshade rendering issue when using Safari in private browsing mode.
Improve the performance of symbol layers on old devices.
TileProvider for raster and raster-dem sources, adding support for PMTiles with raster tiles.import mapboxgl from 'mapbox-gl/esm').line-dasharray not working.scale-factor being applied twice to icons with feature-dependent icon-size.Fix a crash on PowerVR devices.
baseApiUrl is not a Mapbox host.Fix a crash on PowerVR devices.
baseApiUrl is not a Mapbox host.Introduce the TileProvider API, a mechanism for extending GL JS with custom vector tile providers.
TileProvider API, a mechanism for extending GL JS with custom vector tile providers.TileProvider API and an official plugin (mapbox-gl-pmtiles-provider.js) that loads on demand.line-blend-mode property for rendering lines using additive or multiply blending.setWorldview not updating layout properties correctly.*-cutoff-fade-range properties.clip layer not clipping fill-extrusion ambient occlusion.mapbox-gl-unminified.js bundle in the distribution — please switch to either mapbox-gl.js, mapbox-gl-dev.js, or the new esm-min/mapbox-gl.js ESM bundle.spriteFormat Map option — now Mapbox styles will always use vector icons, while non-Mapbox styles will continue using classic raster sprites.Introduce the TileProvider API, a mechanism for extending GL JS with custom vector tile providers.
TileProvider API, a mechanism for extending GL JS with custom vector tile providers.TileProvider API and an official plugin (mapbox-gl-pmtiles-provider.js) that loads on demand.line-blend-mode property for rendering lines using additive or multiply blending.setWorldview not updating layout properties correctly.*-cutoff-fade-range properties.mapbox-gl-unminified.js bundle in the distribution — please switch to either mapbox-gl.js, mapbox-gl-dev.js, or the new esm-min/mapbox-gl.js ESM bundle.spriteFormat Map option — now Mapbox styles will always use vector icons, while non-Mapbox styles will continue using classic raster sprites.Improve memory efficiency by sharing image resources for symbol layers across map tiles.
Fix icons disappearing when changing the color theme.
Improve memory efficiency by sharing image resources for symbol layers across map tiles.
Removed the unused @types/mapbox__point-geometry package that was causing some Typescript builds to fail
@types/mapbox__point-geometry package that was causing some Typescript builds to failPromote elevated lines properties to stable: line-z-offset and line-elevation-reference.
line-z-offset and line-elevation-reference.text-size-scale-range and icon-size-scale-range style properties.Map#setScaleFactor/Map#getScaleFactor methods for controlling symbol layer scaling.text-field.raster-elevation-reference paint property to elevate raster layers relative to ground instead of sea level.line-elevation-ground-scale layout property to scale elevated lines with terrain exaggeration.browserslist.pitch and distance expressions in filters.setFeatureState.Map#setNearClipOffset/Map#getNearClipOffset methods to control the near clip offset when ortohographic projections are used.RasterArrayTileSource#reload() not working correctly.ModelSource.NavigationControl.visibility: none in case properties were changed.fill-extrusion layer, overriding clip layer's behaviour.Promote elevated lines properties to stable: line-z-offset and line-elevation-reference.
line-z-offset and line-elevation-reference.text-size-scale-range and icon-size-scale-range style properties.Map#setScaleFactor/Map#getScaleFactor methods for controlling symbol layer scaling.text-field.RasterArrayTileSource#reload() not working correctly.ModelSource.Fix z-fighting for elevated raster layers.
raster-elevation-reference paint property to elevate raster layers relative to ground instead of sea level.line-elevation-ground-scale layout property to scale elevated lines with terrain exaggeration.browserslist.NavigationControl.visibility: none in case properties were changed.fill-extrusion layer, overriding clip layer's behaviour.Add support for visibility property in clip layers.
visibility property in clip layers.raster-color precision for fine-grained value ranges.icon-size.Add scaleFactor support for images within text-field.
scaleFactor support for images within text-field.showButton option to GeolocateControl that allows hiding the control button.followUserLocation option and setFollowUserLocation method to GeolocateControl to control whether the map follows the user's location.GeolocateControl timeout handling.text-rotate, text-size, and text-offset properties in appearances.shadow-draw-before-layer property to directional light, allowing control over shadow draw order in the layer stack.model-allow-density-reduction property to model layers. (h/t @JoshuaJMoore)icon-text-fit rendering with an incorrect size.icon-size not working correctly with coalesce expressions.raster-color interpolation when using nearest raster-resampling.GeolocateControl error event (h/t @lucavb).dynamic: true mode.AttributionControl links sanitization.icon-size using the default value instead of the layout-defined one.ModelSource.setModels while models are still loading.map.getStyle() output.@mapbox/mapbox-gl-style-spec for direct imports.Add showButton option to GeolocateControl that allows hiding the control button.
showButton option to GeolocateControl that allows hiding the control button.followUserLocation option and setFollowUserLocation method to GeolocateControl to control whether the map follows the user's location.GeolocateControl timeout handling.icon-text-fit rendering with an incorrect size.icon-size not working correctly with coalesce expressions.GeolocateControl error event (h/t @lucavb).Add support for text-rotate, text-size, and text-offset properties in appearances.
text-rotate, text-size, and text-offset properties in appearances.shadow-draw-before-layer property to directional light, allowing control over shadow draw order in the layer stack.model-allow-density-reduction property to model layers. (h/t @JoshuaJMoore)dynamic: true mode.AttributionControl links sanitization.icon-size using the default value instead of the layout-defined one.ModelSource.setModels while models are still loading.map.getStyle() output.@mapbox/mapbox-gl-style-spec for direct imports.Make line-emissive-strength data-driven.
line-emissive-strength data-driven.extra_bounds property of raster and vector sources.model layer.building layer.building layer performance.raster-array layers not working on iOS < 18.4.setData.AttributionControl.Make line-emissive-strength data-driven.
line-emissive-strength data-driven.extra_bounds property of raster and vector sources.Remove experimental flag from model layer.
Introduce experimental Appearances API for managing layer styling based on feature state.
Map setLayerProperty that combines setLayoutProperty & setPaintProperty into one method for convenience.model source and layer.sourcedata event data.queryRenderedFeatures for model layers.GeolocationPosition to geolocate event listeners.scaleFactor.Introduce experimental Appearances API for managing layer styling based on feature state.
Map setLayerProperty that combines setLayoutProperty & setPaintProperty into one method for convenience.model source and layer.queryRenderedFeatures for model layers.Add response headers to the sourcedata event data.
sourcedata event data.GeolocationPosition to geolocate event listeners.scaleFactor.Add queryRasterValue method for querying values in raster-array layers.
queryRasterValue method for querying values in raster-array layers.icon-image-use-theme property.hsla expression performance.queryRasterValue results to 12 decimal digits to fix precision issues."Infinity" and similar ids.GL_INVALID_VALUE console warning on Mapbox Satellite Standard and a few other styles.*-occlusion-opacity properties didn't have any effect.Slightly improve hsla expression performance.
hsla expression performance.queryRasterValue results to 12 decimal digits to fix precision issues.GL_INVALID_VALUE console warning on Mapbox Satellite Standard and a few other styles.*-occlusion-opacity properties didn't have any effect.Add queryRasterValue method for querying values in raster-array layers.
queryRasterValue method for querying values in raster-array layers.icon-image-use-theme property.Nothing published for this version
Imported styles will use the glyphs URL template from the root style instead of their own.
glyphs URL template from the root style instead of their own.split expression to divide a string into an array of substrings based on a specified delimiter.icon-image-cross-fade.raster layers from a single raster-array source.setData on large datasets.Fix rendering of multiple raster layers from a single raster-array source.
raster layers from a single raster-array source.Imported styles will use the glyphs URL template from the root style instead of their own.
glyphs URL template from the root style instead of their own.split expression to divide a string into an array of substrings based on a specified delimiter.icon-image-cross-fade.Nothing published for this version
interpolate expression will interpolate between non-alpha-premultiplied colors. The change might affect raster-particle-color, line-gradient, and heat
interpolate expression will interpolate between non-alpha-premultiplied colors. The change might affect raster-particle-color, line-gradient, and heatmap-color.rgb expression will return non-premultiplied-alpha color.["worldview"] expression, which returns the current worldview of the map.model-translation support for batched model layers.mapbox-gl-rtl-text v0.3.0 plugin not loading in certain configurations.text-variable-anchor disappearing.mouseleave without mouseenter.color-use-theme property of 3D lights.config expressions (h/t @brncsk) #13453.setStyle with the same URL of an import.interpolate expression will interpolate between non-alpha-premultiplied colors. The change might affect raster-particle-color, line-gradient, and heat
interpolate expression will interpolate between non-alpha-premultiplied colors. The change might affect raster-particle-color, line-gradient, and heatmap-color.rgb expression will return non-premultiplied-alpha color.["worldview"] expression, which returns the current worldview of the map.model-translation support for batched model layers.text-variable-anchor disappearing.mouseleave without mouseenter.color-use-theme property of 3D lights.config expressions (h/t @brncsk) #13453.setStyle with the same URL of an import.Add _experimental_ support for rendering 3D road intersections.
wrapTileId property to CustomLayerInterface to control whether tile IDs are wrapped across world copies during rendering.line-pattern-cross-fade, fill-pattern-cross-fade, and fill-extrusion-pattern-cross-fade properties for smooth transitions between pattern images.extra_bounds in TileJSON for more fine-grained control over tile requests, particularly when dealing with sparse data coverage.setData on symbol layers could cause flickering.CustomSourceInterface TypeScript type that was missing in the public interface.line-gradient validation to work not only on GeoJSON, but also on vector tile sources if they have mapbox_clip_start and mapbox_clip_end properties precomputed.styleimagemissing event not firing in certain scenarios.queryRenderedFeatures on Globe at low zoom levels.Add _experimental_ support for rendering 3D road intersections.
setData on symbol layers could cause flickering.CustomSourceInterface TypeScript type that is missing from the public interface.line-gradient validation to work not only on GeoJSON, but also on vector tile sources if they have mapbox_clip_start and mapbox_clip_end properties precomputed.Improve icon loading performance, in particular for landmark icons.
undefined passed in Marker options not falling back to default values.Your coding agent can read these notes before it upgrades. Set up the MCP server →