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
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)One column per quarter.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Fix an issue where the special bundle for CSP-restricted environments was not compatible with further minification in some bundling setups.
Fix the special bundle for CSP-restricted environments that broke in the 2.8.0 release.
Improve memory usage by freeing memory more eagerly after loading tiles.
map.fitBounds(), map.fitScreenCoordinates(), and map.cameraForBounds() incorrectly matching bounds with non-zero bearing. (#11568) (h/t TannerPerrien)border-radius more consistently. (#11423) (h/t nagix)ScaleControl displaying incorrect units with some projections.(#11657)MapDataEvent.isSourceLoaded() to check if specific source has loaded. (#11393)closeOnClick:true. (#11540)map.removeImage() on animated image. (#11580)fill-extrusion layers not rendering on tile borders when used with terrain. (#11530)v0.108.0 to v0.142.0 and enable type-first mode, greatly improving performance of type-checking. (#11426)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Work around a Safari rendering bug by disabling WebGL context antialiasing for Safari 15.4 and 15.5
Enable preloading tiles for camera animation.
line-color: "rgba(r, g, b, 0.5)" instead of line-opacity.setSnapToPixel and getSnapToPixel to indicate rounding a marker to pixel. (#11167) (h/t malekeym)aria-label for interactive markers for improved user accessibility. (#11349)maxzoom. (#11276)map.setProjection (#11279) (h/t lpizzinidev)getBounds sometimes returning invalid LngLat when zooming on a map with terrain. (#11339) (h/t @ted-piotrowski)Improve this Map attribution element. (#11360)Nothing published for this version
Nothing published for this version
Nothing published for this version
Remove Object spread syntax to ensure older build systems continue to work as expected.
Add support for a variety of new map projections beyond the standard Web Mercator. Alternate projections can be used together with all existing styles
albers, equalEarth, equirectangular, lambertConformalConic, naturalEarth and winkelTripel. Change the projection by setting it in the map constructor: new Map({ projection: 'winkelTripel', ... }). (#11124)
"cooperativeGestures": true map option that prevents the map from capturing page scrolling and panning. When enabled, scroll zooming requires ctrl or ⌘ to be pressed and touch panning requires two fingers (#11029, #11116)["pitch"] and ["distance-from-camera"] expressions can now be used within the filter of a symbol layer. (#10795)aria-label in controls, replace aria-pressedwith aria-expanded in the attribution control, interactive markers with popups express an aria-expanded state, and interactive markers have the role "button". (#11064)map.on(), allowing users to get retrieve features under the mouse or touch event based on the order in which they are rendered. (#11114)(h/t @omerbn)map.setFeatureState(...) not updating rendering when terrain is enabled. (#11209)min and max zoom are changed (#11018)null feature values returned as "null" by queryRenderedFeatures(...) (#11110)'raster-resampling': 'nearest' (#11162)Nothing published for this version
Nothing published for this version
Fix an iOS 15 issue where the iOS Safari tab bar interrupts touch interactions.
Added queryRenderedFeatures support to heatmap layers.
queryRenderedFeatures support to heatmap layers. (#10996)line-gradient and line-dasharray paint properties together on line layers. (#10894)preclick event allowing popups to close and open in a new location on one click. (#10926)addClassName, removeClassName and toggleClassName methods to work on popup instances that are not added to the map. (#10889)
maxBounds property not working across the 180th meridian. (#10903)map.getBounds() returning too-large bounds under some conditions. (#10909)Nothing published for this version
Nothing published for this version
Add showUserHeading option to GeolocateControl that draws a triangle in front of the dot to denote both the user's location, and the direction they're
showUserHeading option to GeolocateControl that draws a triangle in front of the dot to denote both the user's location, and the direction they're facing.(#10817) (h/t to @tsuz)text-writing-mode property when using symbol-placement: line text labels. (#10647)
descender and ascender font metrics. (#8781)fill-extrusion dataset with terrain. (#10812)line-center line labels when the anchor is very near to line segment endpoints. (#10776)ImageSource breaking in Firefox/Safari if it's not immediately visible.(#10698)Nothing published for this version
Fix fog flickering when the map option optimizeForTerrain is set to false
Add configurable fog as a root style specification
line-dasharray and line-cap properties. (#10591)text-line-height (#10612)map.queryTerrainElevation(lngLat) when terrain is active (#10602)line-gradient paint property (#10557)map.loadImage followed with a delay by map.addImage failing in Safari and Firefox. (#10524)type=button on attribution button to prevent accidental form submit when map is nested in <form> (#10531)Nothing published for this version
Add testMode Map option that silences errors and warnings generated due to an invalid accessToken. It may be useful when using the library to write un
testMode Map option that silences errors and warnings generated due to an invalid accessToken. It may be useful when using the library to write unit tests. (#10445)geojsonSource.setData(...) performance in Safari (#10417)map.getTerrain() method (#10413)showTerrainWireframe map debug option for displaying terrain wireframe (#10406)geojsonSource.getClusterLeaves(...) (#10403) (h/t henk23)map.getBounds() to return the inset bounds when map padding is set (#10386)GeolocateControl. (#10334) (h/t anderswi)queryRenderedFeatures(...) for fill-extrusions partly behind the camera (#10428)collectResourceTiming errors (#10321)Nothing published for this version
Fixed a font glyphs performance regression on Firefox. (10363)
Added localFontFamily map option that enables local generation of all font glyphs.
localFontFamily map option that enables local generation of all font glyphs. (#10298)localIdeographFontFamily or localFontFamily options. (#10298)optimizeForTerrain map option allowing to use terrain in layer draw-order or performance priority mode. This fixes terrain not always preserving layer draw-order during animations by making the behavior explicit. (#10258)evented.once(eventName) to return a promise if no listener function is provided, which allows using async/await with map events for a simpler and more readable code. (#10203)fill-extrusions when terrain is enabled. (#10293)clusterMaxZoom so that it is not capped by the source maxzoom. (#10300)fill-extrusion querying at low pitch. (#10315)evented.listens returns false when no listener is available. (#10281)Nothing published for this version
Added support for using third-party worker-loader plugins in build systems such as Webpack and Rollup (mapboxgl.workerClass). #10219
mapboxgl.workerClass). #10219mapboxgl.setNow and mapboxgl.restoreNow methods which allow setting custom animation timing for 60 fps, jank-free video recording. #10172ImageSource and dynamically loaded icons didn't work in some cases in Firefox and Safari. #10230map.unproject and map.panBy acted unpredictably in certain cases. #10224map.setStyle couldn't be used to enable terrain. #10177Deprecate Internet Explorer 11, no longer supported from this release. (#8283, #6391)
maxPitch is increased from 60° to 85° which can result in viewing above the horizon line. By default, this area will be drawn transparent but a new sky layer can be added to the map in order to fill this space. The legacy behavior can be achieved by simply adding maxPitch: 60 to the map options when instantiating your map.terrain root level style-spec property or with the function map.setTerrain(). (#1489)atmospheric and gradient.map.getFreeCameraOptions() and map.setFreeCameraOptions().raster and raster-dem tiles when the RTLTextPlugin loads.fill-extrusions.Upgrade minimist to ^1.2.7 to avoid CVE-2021-44906 (#12442) (h/t @Spasfonx)
customAccessToken is provided along with non-Mapbox tiles (#12520)Backport a fix for an iOS 15 issue where the iOS Safari tab bar interrupts touch interactions.
Fix ImageSource not working in some cases in Firefox & Safari. #10230
Improve accessibility by fixing issues reported by WCAG 2.1. #9991
symbol-sort-key. #9751 (h/t @osvodef)Marker clickTolerance option. #9640 (h/t @ChristopherChudzicki)Map hasControl method. #10035Popup setOffset method. #9946 (h/t @jutaz)KeyboardHandler disableRotation and enableRotation methods. #10072 (h/t @jmbott)queryRenderedFeatures didn't properly expose the paint values if they were data-driven. #10074 (h/t @osvodef)fitBounds had an unexpected result with non-zero bearing and uneven padding. #9821 (h/t @allison-strandberg)within expression didn't work in querySourceFeatures. #9933Popup content HTML element was removed on setDOMContent. #10036icon-image is used as a legacy categorical function. #10060Image dataURI's are released. #10118We intend to remove support for Internet Explorer 11 in a future release of GL JS later this year.
Add methods for changing a vector tile source dynamically (e.g. setTiles, setUrl). #8048 (h/t @stepankuzmin)
setTiles, setUrl). #8048 (h/t @stepankuzmin)filter option for GeoJSON sources to filter out features prior to processing (e.g. before clustering). #9864line-gradient for long lines. #9694raster-dem sources to properly support the maxzoom option and overzooming. #9789 (h/t @brendan-ward)easeTo and flyTo animations, freezing the map. #9884 (h/t @andycalder)addImage. #9911 (h/t @francois2metz)promoteId option failed for fill extrusions with defined feature ids. #9863master to main.We intend to remove support for Internet Explorer 11 in a future release of GL JS later this year. Watch this repository for more information on how to prepare your codebase for this change.
Nothing published for this version
Fix a bug that caused map.loaded() to incorrectly return false after a click event.
map.loaded() to incorrectly return false after a click event. (#9825)Add an option to scale the default Marker icon.(#9414) (h/t adrianababakanian)
Marker icon.(#9414) (h/t adrianababakanian)clusterMinPoints option for clustered GeoJSON sources that defines the minimum number of points to form a cluster.(#9748)*-pattern properties on AMD graphics card vendor.(#9681)geometry exceeds allowed extent warning when using Mapbox Streets vector tiles.(#9753)Nothing published for this version
Fix zooming with a double tap in iOS Safari 13
Fix markers interrupting touch gestures (#9675, fixed by #9683)
map.isMoving() returned true while map was not moving (#9647, fixed by #9679)touchmove events from firing during gestures (#9676, fixed by #9685)image expression evaluation which was broken under certain conditions (#9630, fixed by #9685)within expressions in filters not evaluating correctly (#9605, fixed by #9611)undefined paint variable in StyleLayer (#9688) (h/t mannnick24)Upgrade minimist to ^1.2.5 to get fix for security issue CVE-2020-7598 upstream (#9425, fixed by #9425) (h/t watson)
mapboxgl.prewarm() and mapboxgl.clearPrewarmedResources() methods to allow developers to optimize load times for their maps (#9391)index-of and slice expressions to search arrays and strings for the first occurrence of a specified value and return a section of the original array or string (#9450) (h/t lbutler)This release significantly refactors and improves gesture handling on desktop and mobile. Three new touch gestures have been added: two-finger swipe to adjust pitch, two-finger double-tap to zoom out, and tap then drag to adjust zoom with one finger (#9365). In addition, this release brings the following changes and bug fixes:
mousedown and touchstart from interrupting easeTo animations when interaction handlers are disabled (#8725)map.scrollZoom is disabled (#9230)mousedown or touchstart map event and calling .preventDefault() (#9365)doubleClickZoom handler have been removed (#9365)GlyphManager continually re-requesting missing glyph ranges (#8027, fixed by #9375) (h/t oterral)map.queryRenderedFeatures(...) (#9454)background-pattern with data driven expressions (#9518, fixed by #9520)within expression would return inconsistent values for points on tile boundaries (#9411, #9428)within expression would incorrectly evaluate geometries that cross the antimeridian (#9440)Nothing published for this version
Fix a bug #9477 in Map#fitBounds(..) wherein the padding passed to options would get applied twice.
Map#fitBounds(..) wherein the padding passed to options would get applied twice.*-pattern properties reference images added with Map#addImage(..).setPaintProperty.With this release, we're adding a new changelog policy to our contribution guidelines.
With this release, we're adding a new changelog policy to our contribution guidelines.
This release also fixes several long-standing bugs and unintentional rendering behavior with line-pattern. The fixes come with a visual change to how patterns added with line-pattern scale. Previously, patterns that became larger than the line would be clipped, sometimes distorting the pattern, particularly on mobile and retina devices. Now the pattern will be scaled to fit under all circumstances. #9266 showcases examples of the visual differences. For more information and to provide feedback on this change, see #9394.
within expression for testing whether an evaluated feature lies within a given GeoJSON object (#9352).
within expression:<br>
"icon-opacity": ["case", ["==", ["within", "some-polygon"], true], 1, ["==", ["within", "some-polygon"], false], 0]easeTo and flyTo now support padding: PaddingOptions which lets developers shift a map's center of perspective when building floating sidebars (#8638)queryRenderedFeatures now have evaluated property values rather than raw expressions (#9198)line-pattern on all device resolutions and pixel ratios (#9266)LngLatBounds.extend is more flexible because it now accepts objects with lat and lon properties as well as arrays of coordinates (#9293)showTileBoundaries debug text (#9267)addImage(id, image, pixelRatio) by the asset pixel ratio, not the device pixel ratio (#9372)in expression to be false (#9295)feature-state for a layer that has been removed, fixes #8634 (#9305)dir=rtl (#9332)line-dash-array of empty length (#9385)icon-image expression that evaluates to an empty string ('') produced a warning (#9380)popup methods threw errors when accessing the container element before it was created, fixes #9429(#9433)Nothing published for this version
Fixed a bug where all labels showed up on a diagonal line on Windows when using an integrated Intel GPU from the Haswell generation (#9327, fixed by r
Reduce size of line atlas by removing unused channels
showAccuracyCircle option to GeolocateControl that shows the accuracy of the user's location as a transparent circle. Mapbox GL JS will show this circle by default. (#9253) (h/t Meekohi)line-dasharray is now ignored correctly when line-pattern is set (#9189)getClusterExpansionZoom, getClusterChildren, and getClusterLeaves callbacks (#9251)line-dasharray (#9246)trackUserLocation was false and the control was removed before the Geolocation API had returned a location (#9291)promoteId for line layers (#9210)Nothing published for this version
Add promoteId option to use a feature property as ID for feature state
promoteId option to use a feature property as ID for feature state (#8987)mapboxgl.Popup, closeOnMove, that closes the popup when the map's position changes (#9163)map.once() now allows specifying a layer id as a third parameter making it consistent with map.on() (#8875)ImageBitmap and OffscreenCanvas (#8845)symbol-avoid-edges documentation to acknowledge the existence of global collision detection (#9157)in function which has been replaced by the in expression (#9102)GeolocateControl where multiple instances of the control on one page may result in the user location not being updated (#9092)fill-extrusions made from polygons with coincident points and polygons with less than four points (#9138)symbol-sort-key was not used for collisions that crossed tile boundaries (#9054)DragRotateHandler._onMouseUp getting stuck in drag/rotate (#9137)clickTolerance to DragRotateHandler) (#9015) (h/t Yanonix)Nothing published for this version
Fix style validation error messages not being displayed
Add ability to insert images into text labels using an image expression within a format expression: "text-field": ["format", "Some text", ["image", "m
image expression within a format expression: "text-field": ["format", "Some text", ["image", "my-image"], "some more text"] (#8904)icon-text-fit to draw resized images with unstretched corners and borders. (#8997)in expression. It can check if a value is in an array (["in", value, array]) or a substring is in a string (["in", substring, string]) (#8876)minPitch and maxPitch map options (#8834)rotation, rotationAlignment and pitchAlignment options to markers (#8836) (h/t dburnsii)essential parameter to AnimationOptions that can override prefers-reduced-motion: reduce (#8743, fixed by #8883)map.setMinZoom(0) (#9028)Failed to execute 'shaderSource' on 'WebGLRenderingContext' errors (#9017)map.showTileBoundaries rendering (#7314)generateId in conjunction with cluster in a GeoJSONSource (#8223, fixed by #8945)Your coding agent can read these notes before it upgrades. Set up the MCP server →