Mapbox GL JS v2.3.0

Distance fog, elevation querying, and terrain performance improvements

Ricky Reusser

Jun 3, 2021

Mapbox GL JS v2.3.0

Distance fog, elevation querying, and terrain performance improvements


Ricky Reusser


Jun 3, 2021

We’ve just released Mapbox GL JS v2.3 with new 3D features, several performance enhancements and expanded data-driven styling possibilities. Fog gives maps a better sense of depth, designers can simplify their styles with new data-driven styling properties and developers can query elevation data to generate terrain elevation profiles.

No items found.
No items found.


In this release, we’re introducing fog, a subtle rendering effect that improves the visuals of maps. Fading objects with distance is an important visual cue we use to perceive distances.

With fog, map designers now have a way to add significantly more depth to their styles or fit a specific mood with their design. Developers can also leverage fog to optimize their maps, as this effect is an elegant way to reduce the number of tiles loaded at the distance.

Getting started with Fog

Adding fog to a map is very straightforward. It is a root style property that can directly be accessed with map.setFog(..). It comes with three different controls: color, range - adjusting the visual distance where fog is active and dissipates, and horizon-blend - controlling how it blends at the horizon line.

      	range: [2, 12], 
      	color: ‘white’, 
      	horizon-blend: 0.1 

See the style specification for complete documentation, or get started by checking out the example.

Client-side elevation querying

We’ve added a new API to facilitate client-side elevation querying using Digital Elevation Model (DEM) tiles. This new API does not result in any server-side request and directly makes use of the DEM data already available for terrain rendering, making those requests very fast.

Single elevation queries are available with map.queryTerrainElevation(lnglat) and allow to generate elevation profiles without using any extra network resource or service.

See the API Reference for complete documentation or get started by checking out the example.


Reduced GPU memory footprint with terrain

We reduced the GPU memory footprint of terrain by using a shared renderbuffer across all visible tiles of the map viewport. This optimization can save up to 200MB of memory on client applications and is available without any change for developers after upgrading.

Optimized tile cover for terrain

We improved the tile cover when terrain is enabled. At high zoom and highly pitched views, we optimized for memory and speed by reducing the number of DEM tile requests by ~35%. This can be particularly impactful in driving situations where the viewer is close to the ground and the camera is pitched at high angles to match the driver's perspective.

Per-frame batching of heavy DOM operations

Applications dealing with a lot of DOM operations may have performance issues. By using a DOM rendering queue, this release reduces potential reflow by consolidating the updates and applying them once per frame. Markers, popups and other DOM-based map elements can see their update performance improved by a factor of 5-10x.

Data-Driven Styling of line-dasharray and line-cap

With the new release, the line-dasharray and line-cap properties may now take advantage of data-driven styling. For example, you can use dash styling to represent a closed road and keep the information in the same layer as your traffic information. Country borders or road layers that may have previously required six layers can now be styled with just two. This reduction saves you time spent configuring and managing layers.

      "line-dasharray": [
        "match", ["get", "route_status"],
        ["closed" ], ["literal", [2, 2]],
        ["literal", [1]] 

Upgrading to v2.3.0

Mapbox GL JS v2.3.0 is available on CDN and NPM. To update, include the following code in the <head> block of your HTML file:

      <script src=''></script>
      <link href='' rel='stylesheet'/>

GL JS v2.3.0 is integrated and available in Mapbox Studio today. Begin working with fog in your styles by enabling the feature under 3D properties.

See the v2.3.0 release notes for a full list of changes.

Related articles