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 today
17 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
297 releases · first in 2014
Add at-interpolated expression as the interpolated counterpart to the at expression.
at-interpolated expression as the interpolated counterpart to the at expression.altitude marker property to adjust elevation. (h/t @yangtanyu) #13335.getCooperativeGestures and setCooperativeGestures map methods to control cooperative gestures logic after the map is initialized.getGlyphsUrl and setGlyphsUrl map methods to manage the glyphs endpoint URL.pitchRotateKey map option to override the modifier key for rotate and pitch handlers.One column per quarter.
Add support for data-driven *-use-theme properties.
*-use-theme properties.queryRenderedFeatures not working on duplicated model layers.mouseenter and mouseleave with Interactions API.icon-size.Add support for data-driven *-use-theme properties.
*-use-theme properties.queryRenderedFeatures not working on duplicated model layers.Fix vector icons rendering with stretch areas on high DPI devices.
Fix issues when updating feature state on symbol layers.
Fix the display of user-rendered images.
Fix an error when using background patterns on styles with vector icons enabled.
queryRenderedFeatures not working on styles with custom layers.queryRenderedFeatures and querySourceFeatures with featureset, fix filter option to apply to featureset selectors rather than original properties, and add featureNamespace validation.queryRenderedFeatures missing source, sourceLayer and layer properties in resulting features where they should be present.line-join: none.Rename featureset property to target in addInteraction and queryRenderedFeatures options.
featureset property to target in addInteraction and queryRenderedFeatures options.snow and rain style properties.to-hsla expression.*-use-theme property to override the color theme for specific layers.color-theme overrides in imports.mouseenter, mouseover, mouseleave, and mouseout events for addInteraction.featuresets and layers in the Map#queryRenderedFeatures.clip layer is now stable and no longer marked experimental.line-z-offset would sometimes break layer rendering order.Rename featureset property to target in addInteraction and queryRenderedFetures options.
featureset property to target in addInteraction and queryRenderedFetures options.snow and rain style properties.to-hsla expression.*-use-theme property to override the color theme for specific layers.color-theme overrides in imports.mouseenter, mouseover, mouseleave, and mouseout events for addInteraction.featuresets and layers in the Map#queryRenderedFeatures.Add _experimental_ support for style-defined featuresets, an upcoming way to query features in Mapbox Standard and other fragment-based styles.
featuresets, an upcoming way to query features in Mapbox Standard and other fragment-based styles.Map addInteraction/removeInteraction methods that make it easier to manage map interactions like clicking and hovering over features.line-cross-slope and line-elevation-reference properties.scaleFactor map option and setScaleFactor method to increase map label size (useful for improving accessibility or adjusting text size for different devices).line-progress expression in non-data-driven line properties.fill-extrusion-height-alignment and fill-extrusion-base-alignment properties to control fill extrusion top/bottom alignment.addImport calls.symbol-z-offset not working properly.line-emissive-strength not being applied to patterned lines.Minor optimizations to reduce load time.
addImport calls.Add background-pitch-alignment property of the background layer, which is set to map by default but can now be set to viewport. Useful for highlightin
background-pitch-alignment property of the background layer, which is set to map by default but can now be set to viewport. Useful for highlighting individual features by dimming the rest of the map with a semitransparent background.top, right, bottom, and left) (h/t @Ethan-Guttman).retainPadding option for camera movement methods, which can be set to false for pre-v3.4 padding behavior.config expression support in layer filter.symbol-z-offset and symbol-elevation-reference.fill-z-offset property for fill layers.Map#fitBounds for the alternative projections.Map#setPaintProperty and Map#setLayoutProperty methods.string event type in Map event handlers.RequestTransformFunction, ResourceType, and RequestParameters types.fill-extrusion-line-width rendering for large polygonssymbol-z-order is set to auto.minzoom and maxzoom properties were ignored by clip layers.clip layers.cast-shadows property type.setStencilMode-related error in the console with the dev build.Add config expression support in layer filter.
config expression support in layer filter.symbol-z-offset and symbol-elevation-reference.fill-z-offset property for fill layers.Map#fitBounds for the alternative projections.Map#setPaintProperty and Map#setLayoutProperty methods.string event type in Map event handlers.RequestTransformFunction, ResourceType, and RequestParameters types.fill-extrusion-line-width rendering for large polygonssymbol-z-order is set to auto.minzoom and maxzoom properties were ignored by clip layers.clip layers.cast-shadows property type.Add wall rendering mode to the fill-extrusion layer by introducing fill-extrusion-line-width and fill-extrusion-line-alignment properties. Set fill-ex
fill-extrusion layer by introducing fill-extrusion-line-width and fill-extrusion-line-alignment properties. Set fill-extrusion-line-width to a non-zero value to render walls instead of a solid extrusion.circle-blur values.raster-particle-elevation property.data field.clip-layer-scope property to limit clip layer to a specific style fragment.Map idle method to check whether a map is idle.isSourceLoaded flag on sourcedata event for already loaded sources.load event when all tiles fail to load.dynamic mode is updated too frequently.dynamic mode.Map getLayer not working properly with custom layers.line-trim-offset on very long lines.Improve initial load performance.
circle-blur values.data field.isSourceLoaded flag on sourcedata event for already loaded sources.load event when all tiles fail to load.dynamic mode is updated too frequently.Improve 3D models rendering performance.
fill-extrusion-cutoff-fade-range.Revert default behavior of symbol occlusion behind terrain to maintain compatibility. Set icon-occlusion-opacity/text-occlusion-opacity properties to
Revert default behavior of symbol occlusion behind terrain to maintain compatibility. Set icon-occlusion-opacity/text-occlusion-opacity properties to opt-in to new occlusion behavior.
Users relying on the community typings may experience breaking changes. Please remove the @types/mapbox-gl dependency and refer to the v3.5.0 migratio…
@types/mapbox-gl are not fully compatible with the new first-class typings. Users relying on the community typings may experience breaking changes. Please remove the @types/mapbox-gl dependency and refer to the v3.5.0 migration guide for instructions on upgrading, resolving common issues, and asking questions regarding the migration to the first-class typings. We welcome your feedback and contributions to make Mapbox GL JS better.color-theme property and Map setColorTheme method to enable colorization with a lookup table (LUT) images.updateData for GeoJSON sources in dynamic mode.icon-occlusion-opacity and text-occlusion-opacity properties to fade symbols behind models and landmarks.line-occlusion-opacity property to fade lines behind 3D objects.clip layer to filter out rendering data.line-z-offset property for a non-globe view.model-cutoff-fade-range property to control fade out of faraway 3D buildings.line-pattern on long lines and higher zooms.line-trim-color and line-trim-fade-range properties to customize rendering of lines trimmed with line-trim-offset.Map getSlots method for listing available slots of a style.updateData calls.raster-particle layer animation.model-front-cutoff property for Meshopt-encoded models.setTerrain.style.load event missing style property.queryRenderedFeatures on areas with missing DEM tiles when terrain is enabled.Users relying on the community typings may experience breaking changes. Please remove the @types/mapbox-gl dependency and refer to the v3.5.0 migratio…
@types/mapbox-gl are not fully compatible with the new first-class typings. Users relying on the community typings may experience breaking changes. Please remove the @types/mapbox-gl dependency and refer to the v3.5.0 migration guide for instructions on upgrading, resolving common issues, and asking questions regarding the migration to the first-class typings. We welcome your feedback and contributions to make Mapbox GL JS better.color-theme property to enable colorization with a lookup table (LUT) images.icon-occlusion-opacity and text-occlusion-opacity properties to fade symbols behind models and landmarks.line-occlusion-opacity property to fade lines behind 3D objects.clip layer to filter out rendering data.line-z-offset property for a non-globe view.model-cutoff-fade-range property support to control fade out of faraway 3D buildings.updateData calls.raster-particle layer animation.flyTo when prefers-reduced-motion is set.Add dynamic: true option for GeoJSON sources that enables partial update API with source.updateData method. Further optimizations for this mode are ex
dynamic: true option for GeoJSON sources that enables partial update API with source.updateData method. Further optimizations for this mode are expected in future releases.Map setConfig, getConfig, setSchema and getSchema methods for batch setting of style configuration options.config option for the Map constructor and setStyle methods for conveniently setting style configuration options on map initialization.icon-color-saturation, icon-color-contrast, icon-color-brightness-min and icon-color-brightness-max to control symbol layer appearance.line-join mode: none to improve line pattern distortions around joins.model-id property to support URIs (in addition to style-defined model references).devtools UI.flyTo ignoring padding in its options.cameraForBounds on globe view. (h/t @jonasnoki) #13126preloadOnly not preloading tiles from style imports.queryRenderedFeatures for non-integer ID in non-tiled model sourcesmodel-scale property for large number of 3D models.raster-particle layer on globe view.raster-array data.symbol-z-elevate.raster-particle layer on certain Android devices.Add icon-color-saturation, icon-color-contrast, icon-color-brightness-min and icon-color-brightness-max to control symbol layer appearance.
icon-color-saturation, icon-color-contrast, icon-color-brightness-min and icon-color-brightness-max to control symbol layer appearance.line-join mode: none to improve line pattern distortions around joins.model-id property to support URIs (in addition to style-defined model references).cameraForBounds on globe view. (h/t @jonasnoki) #13126preloadOnly not preloading tiles from style imports.queryRenderedFeatures for non-integer ID in non-tiled model sourcesmodel-scale property for large number of 3D models.raster-particle layer on globe view.raster-array data.Add a new raster-array source type, representing a new experimental Mapbox Raster Tile format which encodes series of tiled raster data (such as weath
raster-array source type, representing a new experimental Mapbox Raster Tile format which encodes series of tiled raster data (such as weather time series).raster-particle layer which animates particles of different speed and color based on underlying raster-array data.addImport, moveImport, updateImport, and removeImport API methods.getSlot, and setSlot API methods to control layers' slots.queryRenderedFeatures.raster-elevation support for tiled raster sources.config expression support in fog.maxZoom.setStyle.z offset when the opacity is evaluated at 0 on the zoom change.format expression in the config expression.symbol-sort-key property.Add addImport, moveImport, updateImport, and removeImport API methods.
addImport, moveImport, updateImport, and removeImport API methods.getSlot, and setSlot API methods to control layers' slots.queryRenderedFeatures.raster-elevation support for tiled raster sources.config expression support in fog.maxZoom.setStyle.z offset when the opacity is evaluated at 0 on the zoom change.format expression in the config expression.Improve map loading performance.
devtools: true in Map options.map.areTilesLoaded.fill-extrusion-flood-light-ground-radius property.fill-extrusion-cutoff-fade-range property.config expression chaining through nested styles and other issues related to config scope.map.flyTo with padding option was setting and overriding map's padding.url or tiles is missing from source, i.e. in MapTiler source.config and format expressions not working together.Added imports support in map.areTilesLoaded.
map.areTilesLoaded.fill-extrusion-flood-light-ground-radius property.map.flyTo with padding option was setting and overriding map's padding.url or tiles is missing from source, i.e. in MapTiler source.config expression chaining through nested styles.Fix attribution not being displayed for imported fragments (reintroducing the fix from v3.0.1 that was accidentally missing in v3.1.0).
Fix fill-extrusions not being displayed in alternative projections.
fill-extrusions not being displayed in alternative projections.Improve performance for maps with many textures (such as styles with satellite imagery), fixing excessive memory usage. (h/t @tristan-morris) #12924
raster-elevation property for elevating raster layers to a constant height (e.g. clouds over globe).raster-emissive-strength and fill-extrusion-emissive-strength properties for controlling 3D lighting on buildings and raster layers.Map getConfigProperty method for getting current style config values.config support in terrain options.null.minValue, maxValue, stepValue, values, type) when evaluating config options.center: [0, 0] and zoom: 0 map options were ignored in favor of style settings.slot not taking precedence over the before parameter for layer order."camera-projection": "orthographic" not working in styles with imports.box-sizing: border-box. (h/t @simondriesen) #12982aria-label attribute in attribution control that fails accessibility conformance. (h/t @maggiewachs) #12981load event not firing for the sources whose tiles are 404s.url or tiles for tiled sources during validation.v3.1.0-beta.1null.minValue, maxValue, stepValue, values, type) when evaluating config options.load event not firing for the sources whose tiles are 404s.url or tiles for tiled sources during validation.Improve performance for maps with many textures (such as styles with satellite imagery), fixing excessive memory usage. (h/t @tristan-morris) #12924
raster-elevation property for elevating raster layers to a constant height (e.g. clouds over globe).raster-emissive-strength and fill-extrusion-emissive-strength properties for controlling 3D lighting on buildings and raster layers.Map getConfigProperty method for getting current style config values.config support in terrain options.center: [0, 0] and zoom: 0 map options were ignored in favor of style settings.slot not taking precedence over the before parameter for layer order."camera-projection": "orthographic" not working in styles with imports.box-sizing: border-box. (h/t @simondriesen) #12982aria-label attribute in attribution control that fails accessibility conformance. (h/t @maggiewachs) #12981Fix attribution not being displayed for imported fragments.
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide.
optimizeForTerrain map option (layer rendering on globe and terrain is always optimized now).*-emissive-strength properties for styling layers with the new lighting API.measureLight expression lights configuration property: Create dynamic styles based on lighting conditions.hsl and hsla color expressions: These expressions allow you to define colors using hue, saturation, and lightness format.fill-extrusion-cutoff-fade-range and model-cutoff-fade-range style properties.slots, pre-specified locations in the style, where your layer can be added (e.g., on top of existing land layers but below all labels).config expression: Retrieves the configuration value for the given option.style option is provided to the Map constructor, the Mapbox Standard Style is now enabled as a default.style.import.load event to track the loading of imported style fragments.raster-color paint properties.raster-value expression: Returns the raster value of a pixel computed via raster-color-mix.vertical-range style property.icon-image-cross-fade property, which controls the transitioning between the two variants of an icon image.random expression: Generate random values using this expression. Use this expression to generate random values, which can be particularly helpful for introducing randomness into your map data.distance expression: Returns the shortest distance in meters between the evaluated feature and the input geometry.symbol-z-elevate style property.renderstart event, which, combined with the render event, can be used to measure rendering frame duration.padding is used.tabindex when the map is not interactive; remove role="list" from the attribution control; add role="img" to markers (h/t @kumiko-haraguchi and @aviroopjana).queryRenderedFeatures results on maps with globe and terrain.map hasImage and updateImage after the map was removed.line-border.v3.0.0-rc.2setStyle.queryRenderedFeatures when the model layer is present in the style.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide. Changes since v3.0.0-rc.1:
setConfigProperty not taking effect for certain properties.symbol-z-elevate elevating symbols over invisible fill extrusions (with zero opacity).lights objects.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide. Changes since v3.0.0-beta.5:
slot in custom layers.line-border.raster-color sometimes causing memory issues.fill-extrusion-color causing rendering issues in 3D lighting mode.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide. Changes since v3.0.0-beta.4:
renderstart event, which combined with render event can be used to measure rendering frame duration.setData to animate 3D models.hillshade-illumination-direction to align with light direction if hillshade-illumination-anchor is not set to viewport.fragment: false not to be loaded as basemap imports.map hasImage and updateImage after the map was removed.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide. Changes since v3.0.0-beta.3:
hillshade-emissive-strength property for styling the hillshade layer with the new lighting API.raster-color lookup texture sampling.queryRenderedFeatures results on maps with globe and terrain.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide. Changes since v3.0.0-beta.2:
fill-extrusion-cutoff-fade-range and model-cutoff-fade-range style properties.vertical-range style property.symbol-z-elevate style property.map setLights or setConfigProperty.map transformRequest option not being applied to model URLs.GL_INVALID_OPERATION: Vertex buffer is not big enough for the draw call warnings in certain map views.visibility not being re-evaluated when using setConfigProperty.setStyle on a map with style imports.tabindex when the map is not interactive; remove role="list" from the attribution control; add role="img" to markers (h/t @kumiko-haraguchi and @aviroopjana).transition options from imports.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an erg
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide.
Changes since v3.0.0-beta.1:
style.import.load event to track loading of imported style fragments and ensure style.load is only called once per style.glyphs endpoint specified (falling back to a default Mapbox endpoint).optimizeForTerrain map option (layer rendering on terrain is always optimized now).setStyle when using the Standard style failed.map.removeSource didn't work properly with the Standard style.map.setLayoutProperty not working on a custom layer.padding is used.Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows, nested, configurable styles, and many other v
Mapbox GL JS v3 enables the Mapbox Standard Style, a new realistic 3D lighting system, building shadows, nested, configurable styles, and many other visual enhancements, and an ergonomic API for using a new kind of rich, evolving, configurable map styles and seamless integration with custom data. You can get more information about the new features in the Mapbox GL JS v3 migration guide.
fill-extrusion and other layers to support 3D lighting styling.icon-image-cross-fade property, which controls the transitioning between the two variants of an icon image.raster-color paint properties.hsl and hsla color expressions: These expressions allow you to define colors using hue, saturation, and lightness format.random expression: Generate random values using this expression. Use this expression to generate random values, which can be particularly helpful for introducing randomness into your map data.measureLight expression lights configuration property: Create dynamic styles based on lighting conditions.config expression: Retrieves the configuration value for the given option.raster-value expression: Returns the raster value of a pixel computed via raster-color-mix.distance expression: Returns the shortest distance in meters between the evaluated feature and the input geometry.slots, pre-specified locations in the style, where your layer can be added (e.g., on top of existing land layers but below all labels).style option is provided to the Map constructor, the Mapbox Standard Style is now enabled as a default.Improve performance of symbol layers with identical or no text. Eliminate stuttering when zooming on maps with many identical symbols.
respectPrefersReducedMotion map option (#12694)isPointOnSurface map method to determine if the given point is located on a visible map surface. (#12695)Nothing published for this version
Fix a bug where certain bundling configurations involving Vite or ESBuild could produce a broken build. #12658
Support referrerPolicy option for the transformRequest function when using fetch (#12590) (h/t robertcepa)
referrerPolicy option for the transformRequest function when using fetch (#12590) (h/t robertcepa)prefers-reduced-motion is enabled (#12631)Nothing published for this version
Support draping over terrain and globe in CustomLayer API
setTiles, setUrl). (#12352)line-border-color when used with line-trim-offset (#12461)fitBounds with globe projection (#12488)map.getBounds() returning incorrect bounds with adaptive projections. (#12503)undefined is not an object in coalesceChanges (#12497) (h/t nick-romano)Nothing published for this version
Nothing published for this version
Fix a rare bug where certain diacritical characters could break the rendering of a symbol layer.
Improve performance of patterns and line dashes and improve their appearance when zooming.
cameraForBounds, fitBounds and fitScreenCoordinates camera APIs. (#12367)getBounds when used around the poles with a globe projection. (#12315)*-pattern and line-dasharray properties (#12372)center-to-distance along with terrain. (#12413)Nothing published for this version
Fix support for line breaks in labels that follow line geometries
Nothing published for this version
Add support for cameraForBounds with globe projection
cameraForBounds with globe projection (#12138)fitBounds and fitScreenCoordinates with globe projection (#12211)getBounds with globe projection. (#12286)occludedOpacity allowing the user to set the opacity of a marker that's behind 3D terrain (h/t jacadzaca) (#12258)ImageSource image request when underlying resource is no longer used (#12266) (h/t maciejmatu)LngLatBounds.extend (#12270) (h/t stampyzfanz)GeolocateControl sometimes not working in iOS16 WebView (#12239)map.getStyle() with globe view (#12163)trackPointer is removed (#12230) (h/t camouflagedName)Nothing published for this version
Nothing published for this version
Add new marker styling option rotationAlignment: 'horizon' allowing marker rotation to match the curvature of the horizon in globe view
rotationAlignment: 'horizon' allowing marker rotation to match the curvature of the horizon in globe view (#11894)id expression didn't correctly handle a value of 0 (#12000)cooperativeGestures preventing panning on mobile while in fullscreen. (#12058)setStyle with a globe projection (#12049)Nothing published for this version
Add a workaround in ScaleControl to support localization in browsers without NumberFormat support.
Fix missing lines on some Windows devices.
Add globe projection. This new projection displays the map as a 3d globe and can be enabled by either passing projection: globe to the map constructor
globe projection. This new projection displays the map as a 3d globe and can be enabled by either passing projection: globe to the map constructor or by calling map.setProjection('globe'). All layers are supported by globe except for Custom Layers and Sky.fog with three new style specification properties: high-color, space-color and star-intensity to allow the design of atmosphere around the globe and night skies. (#11590)line-trim-offset that can be used to create a custom fade out with improved update performance over line-gradient. (#11570)GeolocateControl. (#10400) (h/t behnammodi)Map.Title property to locale options to localise the map aria-label. (#11549) (h/t andrewharvey)Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →