mapbox-gl

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.

Breaking changes

• breaking

  Discontinue WebGL 1 support. WebGL 2 is now mandatory for GL JS v3 usage, aligned with universal browser support.

• breaking

  Remove the optimizeForTerrain map option (layer rendering on globe and terrain is always optimized now).

Features and improvements

3D Lights

• Introduced a new 3D Lights API that supports directional and ambient light sources to give you control of lighting and shadows in your map when using 3D objects.

• Add new *-emissive-strength properties for styling layers with the new lighting API.

• Introduced flood lighting for the extruded buildings' walls and the ground beneath them.

• Introduced ambient occlusion to affect the ground beneath the extruded buildings.

• Introduced measureLight expression lights configuration property: Create dynamic styles based on lighting conditions.

• Added support for shadows cast from fill extrusions.

• Introduced hsl and hsla color expressions: These expressions allow you to define colors using hue, saturation, and lightness format.

• Add support for fading out 3D layers in the distance with fill-extrusion-cutoff-fade-range and model-cutoff-fade-range style properties.

Style Composition with Imports

• Introducing support for nested and configurable styles. You can now import other styles into your main style, with updates to imported styles automatically reflected in your main style. Configuration properties can be set for imported styles, making them customizable.

• Introduced concept of 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).

• Introduced config expression: Retrieves the configuration value for the given option.

• When no style option is provided to the Map constructor, the Mapbox Standard Style is now enabled as a default.

• Add a style.import.load event to track the loading of imported style fragments.

Terrain Improvements

• Improve terrain sampling accuracy.

• Improve zooming and panning over dynamic terrain so that it feels smooth.

• Improve performance for styles that use both hillshade layers and terrain.

New Raster Features

• Introduced raster colorization via raster-color paint properties.

• Introduced raster-value expression: Returns the raster value of a pixel computed via raster-color-mix.

…and more!

• Add support for controlling the vertical fog range with vertical-range style property.

• Introduced rounding fill extrusion edges for a smoother appearance.

• Introduced the icon-image-cross-fade property, which controls the transitioning between the two variants of an icon image.

• Introduced 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.

• Introduced distance expression: Returns the shortest distance in meters between the evaluated feature and the input geometry.

• Add support for elevating symbols over buildings & other 3D layers with symbol-z-elevate style property.

• Improve rendering of stars on globe view.

• Add the renderstart event, which, combined with the render event, can be used to measure rendering frame duration.

• Enable zoom-based expressions for model rotation, scale, and translation.

• Optimize shader compilation to reduce stuttering on complex 3D styles.

• Reduce flickering of symbols along lines due to rounding errors.

Bug fixes

• Fix the accuracy of the atmosphere gradient when rendering the globe.

• Fix a bug with horizon placement when map padding is used.

• Fix a bug with horizon rendering on Windows/NVidia.

• Accessibility fixes: remove 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).

• Fix the order of layers in queryRenderedFeatures results on maps with globe and terrain.

• Fix an error when zooming out on certain globe views using the GL JS development bundle.

• Fix an error on map hasImage and updateImage after the map was removed.

• Fix rendering of line layers with data-driven line-border.

• Fix an issue with symbols sometimes not rendering correctly over the terrain on a top-down view.

• Remove duplicate frag precision qualifiers

Changes since v3.0.0-rc.2

Bug fixes

• Fix stale source caches in imports on projection change.

• Fix style not updating properly when adding new imports.

• Fix the breakage of ground effect that occurs when edges cross tile boundaries.

• Fix circle layer depth occlusion not working properly with the orthographic camera.

• Fix diffing of the styles with imports on setStyle.

• Fix GL JS bundle in environments that transpile minified code with async/awaits.

• Fix queryRenderedFeatures when the model layer is present in the style.

• Fix stale 3D lights when removing individually.

• Fix source name collision between imports in symbol layers.

• Remove duplicate frag precision qualifiers.

Features ✨ and improvements

• Improve performance of symbol layers with identical or no text. Eliminate stuttering when zooming on maps with many identical symbols.

• Improve performance of clustered sources: 20% faster loading & 40–60% less memory overhead. Improve performance of symbol collisions.

• Add respectPrefersReducedMotion map option

• Add the isPointOnSurface map method to determine if the given point is located on a visible map surface.

Bug fixes

• Fix inconsistent spacing in the Scale control (#12644) (h/t kathirgounder)

• Fix tiles preloading when a source is not yet loaded

Features ✨ and improvements

• Support referrerPolicy option for the transformRequest function when using fetch (#12590) (h/t robertcepa)

Bug fixes

• Enable anisotropic filtering on tiles beyond 20 degrees pitch to prevent it from compromising image crispness on flat or low-tilted maps.

• Fix LngLatBounds.extend() with literal LngLat object.

• Add arrow characters to the map of verticalized character (#12608) (h/t kkokkojeong)

• Disable panning inertia if prefers-reduced-motion is enabled

Features ✨ and improvements

• Support draping over terrain and globe in CustomLayer API

• Improve the rendering performance of terrain slightly by reducing its GPU memory footprint.

• Add methods for changing a raster tile source dynamically (e.g. setTiles, setUrl).

Bug fixes

• Fix line-border-color when used with line-trim-offset

• Fix potential infinite loop when calling fitBounds with globe projection

• Fix map.getBounds() returning incorrect bounds with adaptive projections.

• Introduce skirts for terrain globe mode

• Fix blur on draped lines while zoom-in

• Fix map pan speed while pinching in

• Fix negative-width diacritics handling

• Fixes undefined is not an object in coalesceChanges (#12497) (h/t nick-romano)

Features ✨ and improvements

• Improve performance of patterns and line dashes and improve their appearance when zooming.

• Improve performance of text and icon placement.

• Improve performance of loading terrain data

• Allow zooming towards terrain at a safe distance without pitching the camera

• Allow for pitch override in cameraForBounds, fitBounds and fitScreenCoordinates camera APIs.

Bug fixes

• Fix getBounds when used around the poles with a globe projection.

• Fix incorrect transition flag in *-pattern and line-dasharray properties

• Fix symbols filtering when using center-to-distance along with terrain.

• Fix fog rendering artifact on lower resolution terrain tiles

• Fix an issue where Geolocate control would throw an error if it's removed before determining geolocation support (#12332) (h/t tmcw)

Features ✨ and improvements

• Add support for cameraForBounds with globe projection

• Add support for fitBounds and fitScreenCoordinates with globe projection

• Improve support for getBounds with globe projection.

• Improve symbol placement performance with globe projection

• Add new marker styling option occludedOpacity allowing the user to set the opacity of a marker that's behind 3D terrain (h/t jacadzaca)

• Cancel ImageSource image request when underlying resource is no longer used (#12266) (h/t maciejmatu)

• Add object literal support in LngLatBounds.extend (#12270) (h/t stampyzfanz)

• Add live performance counters. Mapbox-gl-js v2.11.0 collects certain performance and feature usage counters so we can better benchmark the library and invest in its performance. The performance counters have been carefully designed so that user-level metrics and identifiers are not collected.

Bug fixes

• Fix elevation of pole geometry when exaggerated terrain is used

• Fix GeolocateControl sometimes not working in iOS16 WebView

• Fix map crashing on conformal projections at the south pole

• Fix pixel flickering between tiles on darker styles in globe view.

• Fix occasional missing tiles at bottom of screen during globe-mercator transition

• Fix incorrectly requiring three finger drags to change pitch with cooperative gestures while in fullscreen.

• Fix jumping when scrolling with mouse when crossing the antimeridian on projections that wrap.

• Fix terrain error being fired when using map.getStyle() with globe view

• Fix occasional artifacts appearing in the ocean with terrain or globe enabled.

• Fix invalid AABB calculation as part of the globe tile cover

• Fix incorrect shading of corners in fill extrusions when ambient occlusion is enabled.

• Fix potential performance regression on image source updates

• Fix memory leak when removing maps (#12224) (h/t joewoodhouse)

• Fix updating marker position when toggling between world copied projections and projections without

• Fix missing icons in some styles.

• Fix overwriting all feature ids while setting promoteIds on other layers with an object. (#12322) (h/t yongjun21)

• Fix cursor returning to original state after a popup with trackPointer is removed (#12230) (h/t camouflagedName)

Features ✨ and improvements

• Add new marker styling option rotationAlignment: 'horizon' allowing marker rotation to match the curvature of the horizon in globe view

• Improve panning precision on Globe View and relax constraints on lower zoom levels

• Add unit option to number-format expression (#11839) (h/t varna)

• Add screen reader alert for cooperative gestures warning message.

• Improve rendering performance on globe view

• Improve tile loading performance on low zoom levels

• Improve globe-mercator transition and map load performance with globe projection

Bug fixes

• Fix a bug where id expression didn't correctly handle a value of 0

• Fix precision errors in depth pack/unpack

• Fix cooperativeGestures preventing panning on mobile while in fullscreen.

• Fix misplaced raster tiles after toggling setStyle with a globe projection

• Fix exception on creating map in an iframe with sandbox attribute.

• Fix "improve map" link in the attribution to include location even if map hash is disabled

• Fix Chrome console warnings about ignored event cancel on touch interactions (#12121) (h/t jschaf)

Features

• 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 or by calling map.setProjection('globe'). All layers are supported by globe except for Custom Layers and Sky.

• Extend atmospheric 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.

• Add a new line layer paint property in the style specification: line-trim-offset that can be used to create a custom fade out with improved update performance over line-gradient.

• Add an option for providing a geolocation adapter to GeolocateControl. (#10400) (h/t behnammodi)

• Add Map.Title property to locale options to localise the map aria-label. (#11549) (h/t andrewharvey)

• Allow duplicated coordinates in tile request URLs. (#11441) (h/t ozero)

Bug fixes

• Fix an issue which causes line layers to occasionally flicker.

• Fix markers in fog sometimes becoming more visible when behind terrain.

• Fix an issue where setting terrain exageration to 0 could prevent the zoom to be resolved.

• Copy stylesheet to allow toggling different styles using setStyle without overwriting some of the properties.

Performance improvements

• Improve memory usage by freeing memory more eagerly after loading tiles.

• Improve memory usage by reducing repeated line labels on overscaled tiles.

• Improve performance when placing many symbols on terrain.

Bug fixes

• Fix map.fitBounds(), map.fitScreenCoordinates(), and map.cameraForBounds() incorrectly matching bounds with non-zero bearing. (#11568) (h/t TannerPerrien)

• Improve control button appearance by applying border-radius more consistently. (#11423) (h/t nagix)

• Fix ScaleControl displaying incorrect units with some projections.

• Fix performance regression when animating image sources.

• Fix MapDataEvent.isSourceLoaded() to check if specific source has loaded.

• Fix map not wrapping after moving the map with no inertia.

• Fix popup not removing event listeners when closeOnClick:true.

• Fix camera occasionally intersecting terrain when DEM data loads while zooming. (#11461, #11578)

• Increase clarity of line layers with the terrain on high DPI devices.

• Fix canvas size if more than one parent container has a transform CSS property.

• Fix error on calling map.removeImage() on animated image.

• Fix occasional issue with fill-extrusion layers not rendering on tile borders when used with terrain.

Workflow

• Upgrade Flow from v0.108.0 to v0.142.0 and enable type-first mode, greatly improving performance of type-checking.

Features ✨ and improvements

• Enable preloading tiles for camera animation.

• Improve quality of transparent line layers by removing overlapping geometry artifacts. (#11082). Note: removing that feature can be done by using the line color alpha channel, e.g. line-color: "rgba(r, g, b, 0.5)" instead of line-opacity.

• Add perspective correction for non-rectangular image, canvas and video sources.

• Improve performance of default markers.

• Add marker methods setSnapToPixel and getSnapToPixel to indicate rounding a marker to pixel. (#11167) (h/t malekeym)

• Add a default aria-label for interactive markers for improved user accessibility.

• Add support for sparse tile sets to DEM data sources, when served tiles don't go up to the full maxzoom.

• Allow users to set order of custom attribution.

• Add function call chaining to function map.setProjection (#11279) (h/t lpizzinidev)

Bug fixes

• Fix canvas size to evaluate to expected value when applying the CSS transform property.

• Fix getBounds sometimes returning invalid LngLat when zooming on a map with terrain. (#11339) (h/t @ted-piotrowski)

• Fix rendering of denormalized strings with diacritics.

• Remove redundant title attribute from Improve this Map attribution element.

• Fix a rare terrain flickering issue when using terrain with multiple vector data sources.

Features and improvements

• Add support for a variety of new map projections beyond the standard Web Mercator. Alternate projections can be used together with all existing styles and sources. The projections eliminate distortion as you zoom to make them useful at every scale. Supported projections include albers, equalEarth, equirectangular, lambertConformalConic, naturalEarth and winkelTripel. Change the projection by setting it in the map constructor: new Map({ projection: 'winkelTripel', ... }).

  • Limitations: Non-mercator projections do not yet support terrain, fog, free camera or CustomLayerInterface.

• Add a new "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)

• Add support for dynamic filtering of symbols based on pitch and distance to map center. ["pitch"] and ["distance-from-camera"] expressions can now be used within the filter of a symbol layer.

• Improve user accessibility: conveying only 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".

• Add support for conditionally styling most paint properties according to the presence or absence of specific images.

• Add support for attaching events to multiple layers with 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)

Bug fixes

• Fix map.setFeatureState(...) not updating rendering when terrain is enabled.

• Fix marker positioning before initial map load

• Fix slow tile loading performance on maps with CJK glyphs on certain Chrome/GPU combinations.

• Update NavigationControl when min and max zoom are changed

• Prevent video sources from entering fullscreen on iOS Safari

• Fix a rare triangulation issue that could cause an infinite loop

• Fix null feature values returned as "null" by queryRenderedFeatures(...)

• Fix rendering issue with power of two square images and 'raster-resampling': 'nearest'

Features ✨ and improvements

• Added queryRenderedFeatures support to heatmap layers.

• Added support for using line-gradient and line-dasharray paint properties together on line layers.

• Added preclick event allowing popups to close and open in a new location on one click.

• Improved collision detection for labels along lines, slightly improving label density.

• Improved Popup addClassName, removeClassName and toggleClassName methods to work on popup instances that are not added to the map.

  • ⚠️ Note: Direct modifications to the popup container CSS class no longer persist. These methods should be used instead.

Bug fixes

• Fixed maxBounds property not working across the 180th meridian.

• Fixed map.getBounds() returning too-large bounds under some conditions.

• Fixed markers not updating position when toggling terrain.

• Fixed gap on edge of map on retina displays.

• Fixed SDF images rendering inside text.

• Fixed an issue with slow tile loading performance on maps with CJK glyphs on certain Chrome/GPU combinations.

Features and improvements

• 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 facing.(#10817) (h/t to @tsuz)

• Add support for text-writing-mode property when using symbol-placement: line text labels.

  • Note: This change will bring the following changes for CJK text blocks:

    • 1. For vertical CJK text, all the characters including Latin and Numbers will be vertically placed now. Previously, Latin and Numbers were horizontally placed.

    • 1. For horizontal CJK text, there may be a slight horizontal shift due to the anchor shift.

• Improve character alignment in labels with mixed CJK and Latin characters by adding support for descender and ascender font metrics.

• Improve terrain performance by reducing number of framebuffer switches during draping.

• Improve terrain performance by prioritizing allocation of large render cache batches.

• Improve behavior of vertically aligned line labels with horizontal text by adding stickiness to their flip state, preventing them from flickering.

Bug fixes

• Fix a potential rendering artifact when using custom fill-extrusion dataset with terrain.

• Fix anchor calculation for line-center line labels when the anchor is very near to line segment endpoints.

• Fix ImageSource breaking in Firefox/Safari if it's not immediately visible.

• Fix gradient skybox rendering issue on some ARM Mali GPU's.

Features and improvements

• Add configurable fog as a root style specification

• Add support for data-driven expressions in line-dasharray and line-cap properties.

• Add support for data-driven text-line-height

• Add client-side elevation querying with map.queryTerrainElevation(lngLat) when terrain is active

• Reduce GPU memory footprint when terrain is active by sharing a single depth stencil renderbuffer for all draping

• Optimize tile cover by preventing unnecessary tile loads when terrain is active

• Batch render DOM elements to avoid reflow (#10530, #10567) (h/t zarov)

Bug fixes

• Fix style property transitions not invalidating the terrain render cache

• Fix raster tile expiry data not being retained. (#10494) (h/t andycalder)

• Fix undefined type error when removing line-gradient paint property

• Fix unclustered points in a clustered GeoJSON source incorrectly snapping to a grid at high zoom levels.

• Fix map.loadImage followed with a delay by map.addImage failing in Safari and Firefox.

• Allow conditional display of formatted images in text

• Fix fill-extrusion elevation underflow below sea level

• Fix dashed lines with square line caps.

• Fix markers sometimes throwing an error after being removed from a 3D map. (#10478) (h/t andycalder)

• Set type=button on attribution button to prevent accidental form submit when map is nested in <form>

Features and improvements

• Improve geojsonSource.setData(...) performance in Safari

• Add map.getTerrain() method

• Add showTerrainWireframe map debug option for displaying terrain wireframe

• Document the default limit and offset of geojsonSource.getClusterLeaves(...) (#10403) (h/t henk23)

• (Development) Update dev environment to native ES modules to support Node 14+

Bug fixes

• Fix map.getBounds() to return the inset bounds when map padding is set

• Support flat roofs for fill-extrusions when using custom data sources with terrain

• Fix flickering accuracy circle in GeolocateControl. (#10334) (h/t anderswi)

• Show Mapbox logo if no style is provided for the map

• Switch to using alphabetic baseline for locally-rendered glyphs to avoid misalignment on fonts with large ascenders/descenders.

• Fix incorrect diffing of styles when using raster DEM tile sources

• Fix queryRenderedFeatures(...) for fill-extrusions partly behind the camera

• Fix artifacts caused by negative terrain elevation

• Reset WebGL culling state before drawing custom layers

• Fix DOM event coordinates for scaled containers (#10096) (h/t kawsndriy)

• Fix collectResourceTiming errors

Features and improvements

• Added localFontFamily map option that enables local generation of all font glyphs.

• Introduced high resolution local glyph generation for improved rendering quality of glyphs generated using localIdeographFontFamily or localFontFamily options.

• Added 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.

• Improved performance by slightly shifting the horizon down, reducing the number of tiles loaded for highly-pitched maps.

• Improved 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.

Bug fixes

• Fixed querying of fill-extrusions when terrain is enabled.

• Fixed a bug where close points were sometimes not clustered on higher zoom levels given a small clustering radius. Fixed clusterMaxZoom so that it is not capped by the source maxzoom.

• Fixed blurry map-aligned labels on highly pitched maps with terrain.

• Fixed a race condition when evaluating image expressions by ensuring sprite has loaded before parsing tiles.

• Fixed a bug with fullscreen fill-extrusion querying at low pitch.

• Fixed a regression with the usage of patterns with data-driven styling.

• Ensure evented.listens returns false when no listener is available.

Features and improvements

• Added support for using third-party worker-loader plugins in build systems such as Webpack and Rollup (mapboxgl.workerClass). #10219

• Added mapboxgl.setNow and mapboxgl.restoreNow methods which allow setting custom animation timing for 60 fps, jank-free video recording. #10172

• Removed outdated CSS hacks that no longer apply. #10202

Bug fixes

• Fixed a bug where ImageSource and dynamically loaded icons didn't work in some cases in Firefox and Safari. #10230

• Fixed a bug where map.unproject and map.panBy acted unpredictably in certain cases. #10224

• Fixed a bug where the sky layer didn't take map padding into account. #10201

• Fixed a bug where map.setStyle couldn't be used to enable terrain. #10177

• Fixed a bug where mouse events didn't properly fire during zoom scrolling. #10171

Breaking changes

• breaking

  mapbox-gl-js is no longer under the 3-Clause BSD license. By upgrading to this release, you are agreeing to Mapbox terms of service. Refer to LICENSE.txt for the new licensing terms and details. For questions, contact our team at support.mapbox.com.

• breaking

  Beginning with v2.0.0, a billable map load occurs whenever a Map object is initialized. Before updating an existing implementation from v1.x.x to v2.x.x, please review the pricing documentation to estimate expected costs.

• deprecated

  Deprecate Internet Explorer 11, no longer supported from this release. (#8283, #6391)

• breaking

  Support for unlocked pitch up to 85°. The default 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.

Features and improvements

• Add 3D terrain feature. All layer types and markers can now be extruded using the new terrain root level style-spec property or with the function map.setTerrain().

• Add support for unlocked pitch up to 85° (previously 60°).

• Add a new sky layer acting as an infinite background above the horizon line. This layer can be used from the style-spec and has two types: atmospheric and gradient.

• Add a free form camera API, allowing for more complex camera manipulation in 3D, accessible using map.getFreeCameraOptions() and map.setFreeCameraOptions().

• Improve performance by adopting a two-phase tile loading strategy, prioritizing rendering of non-symbol layers first.

• Improve performance by avoiding parsing vector tiles that were already aborted.

• Improve performance by adopting a preemptive shader compilation strategy.

• Improve performance by disabling fade-in animation for symbols and raster tiles on initial map load.

• Improve performance by defaulting to 2 workers on all platforms.

• Improve performance by loading tiles on the main thread at initial map load.

• Improve performance by using better worker task scheduling.

Bug fixes

• Avoid reloading raster and raster-dem tiles when the RTLTextPlugin loads.

• Add runtime evaluation of label collision boxes for more accurate symbol placement at fractional zoom levels and tilted views.

• Fix tile cache size for terrain DEM sources.

• Prevent holding on to DEM memory on the worker.

• Reduce memory used by fill-extrusions.

Workflow

• Run render tests in browser.

Features and improvements

• Improve accessibility by fixing issues reported by WCAG 2.1. #9991

• Improve accessibility when opening a popup by immediately focusing on the content. #9774 (h/t @watofundefined)

• Improve rendering performance of symbols with symbol-sort-key. #9751 (h/t @osvodef)

• Add Marker clickTolerance option. #9640 (h/t @ChristopherChudzicki)

• Add Map hasControl method. #10035

• Add Popup setOffset method. #9946 (h/t @jutaz)

• Add KeyboardHandler disableRotation and enableRotation methods. #10072 (h/t @jmbott)

Bug fixes

• Fix a bug where queryRenderedFeatures didn't properly expose the paint values if they were data-driven. #10074 (h/t @osvodef)

• Fix a bug where attribution didn't update when layer visibility changed during zooming. #9943

• Fix a bug where hash control conflicted with external history manipulation (e.g. in single-page apps). #9960 (h/t @raegen)

• Fix a bug where fitBounds had an unexpected result with non-zero bearing and uneven padding. #9821 (h/t @allison-strandberg)

• Fix HTTP support when running GL JS against Mapbox Atlas. #10090

• Fix a bug where the within expression didn't work in querySourceFeatures. #9933

• Fix a bug where Popup content HTML element was removed on setDOMContent. #10036

• Fix a compatibility bug when icon-image is used as a legacy categorical function. #10060

• Reduce rapid memory growth in Safari by ensuring Image dataURI's are released. #10118

Note on IE11

We intend to remove support for Internet Explorer 11 in a future release of GL JS later this year.

Features and improvements

• Add methods for changing a vector tile source dynamically (e.g. setTiles, setUrl). #8048 (h/t @stepankuzmin)

• Add a filter option for GeoJSON sources to filter out features prior to processing (e.g. before clustering). #9864

• Vastly increase precision of line-gradient for long lines. #9694

• Improve raster-dem sources to properly support the maxzoom option and overzooming. #9789 (h/t @brendan-ward)

Bug fixes

• Fix a bug where bearing snap interfered with easeTo and flyTo animations, freezing the map. #9884 (h/t @andycalder)

• Fix a bug where a fallback image was not used if it was added via addImage. #9911 (h/t @francois2metz)

• Fix a bug where promoteId option failed for fill extrusions with defined feature ids. #9863

Workflow

• Renamed the default development branch from master to main.

Note on IE11

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.

Features and improvements

• Add an option to scale the default Marker icon.(#9414) (h/t adrianababakanian)

• Improving the shader compilation speed by manually getting the run-time attributes and uniforms.

• Added clusterMinPoints option for clustered GeoJSON sources that defines the minimum number of points to form a cluster.

Bug fixes

• Fix a bug where map got stuck in a DragRotate interaction if it's mouseup occurred outside of the browser window or iframe.

• Fix potential visual regression for *-pattern properties on AMD graphics card vendor.

• Fix zooming with a double tap on iOS Safari 13.

• Removed a misleading geometry exceeds allowed extent warning when using Mapbox Streets vector tiles.

• Fix reference error when requiring the browser bundle in Node.

Bug fixes

• Fix markers interrupting touch gestures (#9675, fixed by #9683)

• Fix bug where map.isMoving() returned true while map was not moving (#9647, fixed by #9679)

• Fix regression that prevented touchmove events from firing during gestures (#9676, fixed by #9685)

• Fix image expression evaluation which was broken under certain conditions (#9630, fixed by #9685)

• Fix nested within expressions in filters not evaluating correctly (#9605, fixed by #9611)

• Fix potential undefined paint variable in StyleLayer (#9688) (h/t mannnick24)

Features

• Add mapboxgl.prewarm() and mapboxgl.clearPrewarmedResources() methods to allow developers to optimize load times for their maps

• Add 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)

• Correctly set RTL text plugin status if the plugin URL could not be loaded. This allows developers to add retry logic on network errors when loading the plugin

Gestures

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:

• It's now possible to interact with multiple maps on the same page at the same time

• Fix map jump when releasing one finger after pinch zoom

• Stop mousedown and touchstart from interrupting easeTo animations when interaction handlers are disabled

• Stop mouse wheel from interrupting animations when map.scrollZoom is disabled

• A camera change can no longer be prevented by disabling the interaction handler within the camera change event. Selectively prevent camera changes by listening to the mousedown or touchstart map event and calling .preventDefault()

• Undocumented properties on the camera change events fired by the doubleClickZoom handler have been removed

Improvements and bug fixes

• Line labels now have improved collision detection, with greater precision in placement, reduced memory footprint, better placement under pitched camera orientations

• Fix GlyphManager continually re-requesting missing glyph ranges (#8027, fixed by #9375) (h/t oterral)

• Avoid throwing errors when calling certain popup methods before the popup element is created

• Fix a bug where fill-extrusion features with colinear points were not returned by map.queryRenderedFeatures(...)

• Fix a bug where using feature state on a large input could cause a stack overflow error

• Fix exception when using background-pattern with data driven expressions (#9518, fixed by #9520)

• Fix a bug where UI popups were potentially leaking event listeners (#9498) (h/t mbell697)

• Fix a bug where the within expression would return inconsistent values for points on tile boundaries (#9411, #9428)

• Fix a bug where the within expression would incorrectly evaluate geometries that cross the antimeridian

• Fix possible undefined exception on paint variable of style layer (#9437) (h/t mannnick24)

• security

  Upgrade minimist to ^1.2.5 to get fix for security issue CVE-2020-7598 upstream (#9425, fixed by #9425) (h/t watson)

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.

Features

• Add within expression for testing whether an evaluated feature lies within a given GeoJSON object (#9352).

  • We are aware of an edge case in which points with wrapped coordinates (e.g. longitude -185) are not evaluated properly. See (#9442) for more information.

  • An example of the within expression:
    "icon-opacity": ["case", ["==", ["within", "some-polygon"], true], 1, ["==", ["within", "some-polygon"], false], 0]

• Map API functions such as easeTo and flyTo now support padding: PaddingOptions which lets developers shift a map's center of perspective when building floating sidebars

Improvements

• Results from queryRenderedFeatures now have evaluated property values rather than raw expressions

• Improve scaling of patterns used in line-pattern on all device resolutions and pixel ratios

• Slightly improve GPU memory footprint

• LngLatBounds.extend is more flexible because it now accepts objects with lat and lon properties as well as arrays of coordinates

• Reduce bundle size and improve visual quality of showTileBoundaries debug text

Bug fixes

• Correctly adjust patterns added with addImage(id, image, pixelRatio) by the asset pixel ratio, not the device pixel ratio

• Allow needle argument to in expression to be false

• Fix exception thrown when trying to set feature-state for a layer that has been removed, fixes #8634

• Fix a bug where maps were not displaying inside elements with dir=rtl

• Fix a rendering error for very old versions of Chrome (ca. 2016) where text would appear much bigger than intended

• Prevent exception resulting from line-dash-array of empty length

• Fix a bug where icon-image expression that evaluates to an empty string ('') produced a warning

• Fix a bug where certain popup methods threw errors when accessing the container element before it was created, fixes #9429

Features and improvements

• Reduce size of line atlas by removing unused channels

• Prevent empty buffers from being created for debug data when unused

• Add space between distance and unit in scale control (#9276) (h/t gely) and (#9284) (h/t pakastin)

• Add a 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)

• Implemented a new tile coverage algorithm to enable level-of-detail support in a future release

Bug fixes

• line-dasharray is now ignored correctly when line-pattern is set

• Fix line distances breaking gradient across tile boundaries

• Fix a bug where lines with duplicate endpoints could disappear at zoom 18+

• Fix a bug where Ctrl-click to drag rotate the map was disabled if the Alt, Cmd or Windows key is also pressed

• Pass errors to getClusterExpansionZoom, getClusterChildren, and getClusterLeaves callbacks

• Fix a rendering performance regression

• Fix visual artifact for line-dasharray

• Fixed a bug in the GeolocateControl which resulted in an error when trackUserLocation was false and the control was removed before the Geolocation API had returned a location

• Fix promoteId for line layers

• Improve accuracy of distance calculations (#9202) (h/t Meekohi)

Features

• Add promoteId option to use a feature property as ID for feature state

• Add a new constructor option to mapboxgl.Popup, closeOnMove, that closes the popup when the map's position changes

• Allow creating a map without a style (an empty one will be created automatically) ( h/t @stepankuzmin )

• map.once() now allows specifying a layer id as a third parameter making it consistent with map.on()

Improvements

• Improve performance of raster layers on large screens

• Improve performance for hillshade and raster layers by implementing a progressive enhancement that utilizes ImageBitmap and OffscreenCanvas

• Improve performance for raster tile rendering by using the stencil buffer

• Update symbol-avoid-edges documentation to acknowledge the existence of global collision detection

• Remove reference to in function which has been replaced by the in expression

Bug Fixes

• Change the type of tile id key to string to prevent hash collisions

• Prevent changing bearing via URL hash when rotation is disabled

• Fix URL hash with no bearing causing map to fail to load

• Fix bug in GeolocateControl where multiple instances of the control on one page may result in the user location not being updated

• Fix query fill-extrusions made from polygons with coincident points and polygons with less than four points

• Fix bug where symbol-sort-key was not used for collisions that crossed tile boundaries

• Fix bug in DragRotateHandler._onMouseUp getting stuck in drag/rotate

• Fix "Click on Compass" on some mobile devices (add clickTolerance to DragRotateHandler) (#9015) (h/t Yanonix)

Features

• Add ability to insert images into text labels using an image expression within a format expression: "text-field": ["format", "Some text", ["image", "my-image"], "some more text"]

• Add support for stretchable images (aka nine-part or nine-patch images). Stretchable images can be used with icon-text-fit to draw resized images with unstretched corners and borders.

• Add 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])

• Add minPitch and maxPitch map options

• Add rotation, rotationAlignment and pitchAlignment options to markers (#8836) (h/t dburnsii)

• Add methods to Popup to manipulate container class names (#8759) (h/t Ashot-KR)

• Add configurable inertia settings for panning (h/t @aMoniker)

• Add ability to localize mapbox UI controls (#8095) (h/t dmytro-gokun)

• Add LatLngBounds.contains() method (#7512, fixed by #8200)

• Add option to load rtl-text-plugin lazily

• Add essential parameter to AnimationOptions that can override prefers-reduced-motion: reduce (#8743, fixed by #8883)

Improvements

• Allow rendering full world smaller than 512px. To restore the previous limit call map.setMinZoom(0)

• Add an es modules build of for mapbox-gl-style-spec in dist/ (#8247) (h/t ahocevar)

• Add 'image/webp,/' accept header to fetch/ajax image requests when webp supported

• Improve documentation for setStyle, getStyle, and isStyleLoaded

Bug Fixes

• Fix map rendering after addImage and removeImage are used to change a used image

• Fix visibility of controls in High Contrast mode in IE

• Fix customizable url hash string in IE 11 (#8990) (h/t pakastin)

• Allow expression stops up to zoom 24 instead of 22 (#8908) (h/t nicholas-l)

• Fix alignment of lines in really overscaled tiles

• Fix Failed to execute 'shaderSource' on 'WebGLRenderingContext' errors

• Make expression validation fail on NaN

• Fix setLayerZoomRange bug that caused tiles to be re-requested (#7865, fixed by #8854)

• Fix map.showTileBoundaries rendering

• Fix using generateId in conjunction with cluster in a GeoJSONSource (#8223, fixed by #8945)

• Fix opening popup on a marker from keyboard

• Fix error thrown when request aborted (#7614, fixed by #9021)

• Fix attribution control when repeatedly removing and adding it

This patch introduces two workarounds that address longstanding issues related to unbounded memory growth in Safari, including #8771 and #4695. We’ve identified two memory leaks in Safari: one in the CacheStorage API, addressed by #8956, and one in transferring data between web workers through Transferables, addressed by #9003.

Improvements

• Implement workaround for memory leak in Safari when using the CacheStorage API.

• Implement workaround for memory leak in Safari when using Transferable objects to transfer ArrayBuffers to WebWorkers. If GL-JS detetcts that it is running in Safari, the use of Transferables to transfer data to WebWorkers is disabled.

• Improve animation performance when using map.setData. (#8913) (h/t msbarry)

Features

• Add disabled icon to GeolocateControl if user denies geolocation permission. #8871)

• Add outofmaxbounds event to GeolocateControl, which is emitted when the user is outside of map.maxBounds (#8756) (h/t MoradiDavijani)

• Add mapboxgl.getRTLTextPluginStatus() to query the current status of the rtl-text-plugin to make it easier to allow clearing the plugin when necessary. (ref. #7869)

• Allow hash Map option to be set as a string, which sets the map hash in the url to a custom query parameter. (#8603) (h/t SebCorbin)

Improvements

• Fade symbols faster when zooming out quickly, reducing overlap.

• Reduce memory usage for vector tiles that contain long strings in feature properties.

Bug Fixes

• Fix text-variable-anchor not trying multiple placements during collision with icons when icon-text-fit is enabled.

• Fix icon-text-fit not properly respecting vertical labels.

• Fix opacity interpolation for composition expressions.

• Fix rotate and pitch events being fired at the same time.

• Fix memory leaks that occured during tile loading and map removal.(#8813 and #8850)

• Fix web-worker transfer of ArrayBuffers in environments where instanceof ArrayBuffer fails.(e.g cypress)