npm / mapbox-gl

mapbox-gl

What changed in mapbox-gl 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-25.

5 breaking5 new APIs and options9 performance4 behavior and defaults18 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.6 on npm

mapbox-gl 341 changes

Breaking changes 5

Removed because right-to-left text is now supported out of the box.
3.33.0release notes
Parent-tile symbols are no longer placed when using global placement.
3.33.0release notes
The type is removed as right-to-left text is now supported out of the box.
3.33.0release notes
Removed because right-to-left text is now supported out of the box.
3.33.0release notes
The base size of icons is calculated at the tile zoom level with the largest text size, so icons can be smaller when text size depends on zoom.
3.33.0release notes

New APIs and options 5

Controls can be offset from their corner using an offset object with x and y values.
3.33.0release notes
Right-to-left text, such as Arabic and Hebrew, is supported out of the box; a small WebAssembly module loads the first time it appears on the map.
3.33.0release notes
CustomLayerInterface render and prerender receive a CustomLayerRenderParameters object as an eighth argument, exposing projectionMatrix, viewMatrix, globeClippingPlane, and globeCenterInScreenPixels.
3.32.0release notes
Debug visualization is supported when using global placement.
3.32.0release notes
Custom layers gain support for emissive MRT.
3.31.0release notes

Performance 9

Map load performance is improved for 3D Lanes.
3.33.0release notes
Line rendering performance improves by using a uniform instead of a shader permutation.
3.33.0release notes
Memory use and map load time are improved, especially for 3D layers.
3.33.0release notes
Preloading the Meshopt decoder earlier improves 3D styles load time.
3.32.0release notes
Requesting the icon set earlier and parsing icons on demand improves map load time.
3.32.0release notes
More aggressive chunk preloading slightly improves map load time.
3.32.0release notes
Style parsing is faster.
3.32.0release notes
GeoJSON memory footprint is significantly improved, reducing memory use for developers working with GeoJSON.
3.31.0release notes
Landmark model memory usage is reduced.
3.31.0release notes

Behavior and default changes 4

Global placement debug information is extended.
3.33.0release notes
Global placement supports transitions between globe and Mercator projections.
3.32.0release notes
Symbol fading is supported when using global placement.
3.32.0release notes
The experimental flag is removed from raster-allow-draping.
3.31.0release notes

Fixes and other changes 18

Fixes collision boxes not matching rotated symbols that use appearances with a layout icon-rotate or text-rotate.
3.33.0release notes
Fixes a rendering issue that could occur when drawing thousands of data-driven lines and symbols.
3.33.0release notes
Fixes transparent building and fill-extrusion layers blending the same pixel twice where they cover the same buildings.
3.33.0release notes
Fixes incorrect rendering of geometries past longitude -+360 or latitude +-85.
3.33.0release notes
In projections other than Mercator or globe, map-aligned icon rotation is now measured from true north.
3.33.0release notes
Fixes a severe performance regression when updating data-driven line layers.
3.33.0release notes
Fixes symbol fading not finishing when global placement is used.
3.33.0release notes
In projections other than Mercator or globe, map-aligned text rotation is now measured from true north.
3.33.0release notes
extra_bounds is respected on all TileJSON source types.
3.32.0release notes
Placing symbols with no text no longer throws an error.
3.32.0release notes
Fixes transitions for light, fog, snow, and rain.
3.32.0release notes
Fixes a regression where map.remove() could retain the map instance in memory.
3.32.0release notes
Setting padding as a side effect in a preloadOnly animation is fixed.
3.32.0release notes
Fixes chunk loading when raster-array is unused.
3.32.0release notes
Headers and credentials are no longer dropped from PMTiles requests.
3.32.0release notes
Headers and credentials are no longer dropped when loading GL model (GLTF) resources.
3.32.0release notes
Features render at the correct position when a layer uses a within filter with a projection other than Mercator or globe.
3.32.0release notes
Fixes removeSource throwing under globe projection.
3.31.0release notes