Efficient pitched tile loading, Precise CJK labels, and JS Promises: Mapbox GL JS v2.1.1

No items found.

Feb 10, 2021

Efficient pitched tile loading, Precise CJK labels, and JS Promises: Mapbox GL JS v2.1.1


No items found.


Feb 10, 2021

We've just released Mapbox GL JS v2.1.1, with efficient pitched tile loading, improved rendering precision for CJK labels, 3D interaction enhancements, JS Promises for map events, and several other bug fixes and improvements.

More efficient tile loading in pitched views

We improved performance of pitched views by slightly shifting the position of the horizon line. The new behavior results in very little visual difference, but reduces the number of tiles in view by up to 20%. This results in higher frame rates, shorter load times and less memory consumption for highly pitched maps.

A small change to the horizon position can improve tile loads by up to 20%

Improved precision when rendering Chinese, Japanese and Korean labels

We’ve made several changes to make CJK (Chinese, Japanese and Korean) labels look better.

First, we introduced a new localFontFamily map option that allows you to turn on local font rendering for all characters, not just ideographic glyphs (that are locally rendered by default). This fixes issues with character alignment when CJK glyphs are mixed together with other characters like numbers, and makes such labels more consistent in appearance.


Additionally, the resolution of locally rendered labels was doubled, making corresponding labels crisper and more legible, especially at smaller font sizes. In the video below, you can see that the Japanese text is much crisper and has fewer artifacts in v2.1.1.

Preserve draw order with 3D terrain

3D terrain added in v2 also had the side effect of introducing rendering inconsistencies for certain maps during user interactions. When rendering 3D terrain, GL JS attempts to render multiple layers in a single batch to achieve the best performance possible. This can result in layers being reordered during rendering. v2.1.1 fixes this problem, providing a consistent rendering experience inclusive of user interaction events.

If layer order must be maintained, you can now set the new map property optimizeForTerrain:false in order to ensure the correct order.

Previous behavior not preserving draw order during user interaction

New behavior during user interaction, in draw order priority

Better map-aligned labels on pitched maps with 3D terrain

The legibility of labels on 3D terrain has been improved when using text-pitch-alignment:”map”. The previous implementation over-adjusted text sharpness to compensate for map pitch, resulting in blurry text that was particularly noticeable on highly pitched views.

Before: note the blurry labels
After: labels are now legible

Querying of fill-extrusions on 3D maps

map.queryRenderedFeatures() now supports querying of features for all layer types with 3D terrain. This lets you build interactive 3D maps with the same performance you’ve come to expect from 2D maps.

Promises and Async/Await with map events

The map.once method, which allows you to run code once a given event fires, now returns a Promise if you don’t provide a callback. This small change enables a more ergonomic way to program GL JS using the modern async/await JavaScript pattern, replacing a mess of nested callbacks.


const map = new mapboxgl.Map({...});

map.on('load', function() {
  map.addSource('dem', {type: 'raster-dem', url: 'mapbox://mapbox.mapbox-terrain-dem-v1'});
  map.setTerrain({source: 'dem', exaggeration: 1.5});

  map.on('idle', function() {


const map = new mapboxgl.Map({...});

await map.once('load');

map.addSource('dem', {type: 'raster-dem', url: 'mapbox://mapbox.mapbox-terrain-dem-v1'});
map.setTerrain({source: 'dem', exaggeration: 1.5});

await map.once('idle');


Improved clustered points on high zoom levels

We fixed an issue with point clustering where points were sometimes not clustered on higher zoom levels given a small cluster radius, causing them to disappear. Clustering is also updated to occur at all zoom levels, including the maximum zoom level given by clusterMaxZoom.

Fix for a race condition when evaluating image expressions

v2.1.1 fixes a race condition bug that occurred when the image expression is used with layers defined within a map style. Previously, it was possible for these expressions to be evaluated before the sprite images became available, resulting in inconsistent rendering of the images. This new release ensures that the sprite is available before evaluating image expressions.

Upgrading to v2.1.1

Mapbox GL JS v2.1.1 is available on CDN: include the JavaScript and CSS files in the <head> block of your HTML file to upgrade.

<script src='https://api.mapbox.com/mapbox-gl-js/v2.1.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v2.1.1/mapbox-gl.css' rel='stylesheet'/>

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Block quote

Ordered list

  1. Item 1
  2. Item 2
  3. Item 3

Unordered list

  • Item A
  • Item B
  • Item C

Text link

Bold text




No items found.
No items found.

Related articles