# What changed in mapbox-gl

> 41 changes in mapbox-gl 3 from its official release notes, upgrade guides and advisories: 5 breaking, 5 new APIs and options. Each one cited. Sources checked 2026-10-25. HTML: https://unstale.sh/npm/mapbox-gl/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## mapbox-gl 3

### Breaking changes

- Removed because right-to-left text is now supported out of the box. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Parent-tile symbols are no longer placed when using global placement. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- The type is removed as right-to-left text is now supported out of the box. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Removed because right-to-left text is now supported out of the box. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- 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.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)

### New APIs and options

- Controls can be offset from their corner using an `offset` object with `x` and `y` values. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- 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.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- CustomLayerInterface render and prerender receive a CustomLayerRenderParameters object as an eighth argument, exposing projectionMatrix, viewMatrix, globeClippingPlane, and globeCenterInScreenPixels. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- Debug visualization is supported when using global placement. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- Custom layers gain support for emissive MRT. (3.31.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.31.0)

### Performance

- Map load performance is improved for 3D Lanes. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Line rendering performance improves by using a uniform instead of a shader permutation. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Memory use and map load time are improved, especially for 3D layers. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Preloading the Meshopt decoder earlier improves 3D styles load time. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- Requesting the icon set earlier and parsing icons on demand improves map load time. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- More aggressive chunk preloading slightly improves map load time. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- Style parsing is faster. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- GeoJSON memory footprint is significantly improved, reducing memory use for developers working with GeoJSON. (3.31.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.31.0)
- Landmark model memory usage is reduced. (3.31.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.31.0)

### Behavior and default changes

- Global placement debug information is extended. (3.33.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.33.0)
- Global placement supports transitions between globe and Mercator projections. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- Symbol fading is supported when using global placement. (3.32.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.32.0)
- The experimental flag is removed from raster-allow-draping. (3.31.0) — [release notes](https://github.com/mapbox/mapbox-gl-js/releases/tag/v3.31.0)

### Fixes and other changes

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