Customers can now choose the projection of their interactive web maps. Adaptive Projections are among the many new features available now in Mapbox GL JS v2.6 and they allow designers to create more accurate visualizations at every zoom level. Projections allow mapmakers to tell a better story with their data and meet style requirements. The New York Times uses the Albers projection for their national election maps, while the National Geographic Society uses Winkel Tripel for their world maps.

Until now, changing the map projection on web maps required sacrificing interactivity or developing complex custom implementations. Adaptive Projections lets these organizations and everyone use projections, without complex workarounds, with a single line of code.

A map projection is a way to flatten the globe's surface onto a screen. While flattening, distortion is inevitable—some parts will stretch and some will squish. Nearly all web maps use the Mercator projection, which maintains angles and shapes and works well for high zoom levels. But Mercator distorts the size of regions on lower zoom levels, like when looking at data on an national or global overview map. For example, Greenland is visually the same size as Africa on a Mercator map, even though it is 14 times smaller in reality.

An equal area projection like Equal Earth or a compromise projection like Winkel Tripel corrects this distortion, showing continents and countries at their true size relative to each other. Customers can now choose a projection that maintains size, maintains shape, or a bit of both. GL JS supports the Albers, Lambert Conformal Conic, Equal Earth, Natural Earth, Winkel Tripel, Equirectangular, and Mercator projections.

No matter which projection developers choose, Adaptive Projections will seamlessly transition to Mercator as users zoom in. Now developers can easily make overview maps that communicate data accurately, but also allow drilling into the data at a detailed level.

Adaptive projections can be used with any existing map style and all existing tilesets processed with the Mapbox Tiling Service. With GL JS v2.6, developers can skip data transformations and hacky work-arounds, and use a single library for all map visualizations. Change the projection of any map with one line of code, or using the map style editor in Mapbox Studio.

new mapboxgl.Map({
    projection: {name: "winkelTripel"},
    ...
});

New features in GL JS v2.6 goes beyond Adaptive Projections and includes better options for gesture handling on mobile, 3D labeling improvements, and more.

Cooperative Gesture Handling

While attempting to scroll a page with a full-width map, end users may get frustrated by their scroll or zoom interactions acting on the map, instead of the web page. Cooperative gesture handling simplifies user interaction between the web page and the map. Developers no longer need to implement custom event handling to get a consistent experience across multiple device types.

When cooperativeGestures is enabled, scroll-to-zoom requires using the control or command key while scrolling to zoom the map, and panning on touch devices requires using two fingers to pan the map. When cooperativeGestures is disabled, the user is unable to continue scrolling to contents below a map until moving the cursor, or their finger, off of the map.  

To start using cooperative gestures, set cooperativeGestures to true when instantiating a map. By default, cooperativeGestures is set to false.

new mapboxgl.Map({
    cooperativeGestures: true,
    ...
});

3D Labeling Improvements

Map designers have two new ways to design the right label treatment and density for 2D and 3D views. With the pitch and distance-from-camera expressions, designers can create symbol layers with dynamic filters that are evaluated continuously as the map camera changes.

Switch labels to use leader lines by setting complimentary pitch limits on two different layers.

// Set the non-elevated layer to show at pitch <= 60 deg
map.setFilter(“natural-point-label”, [“<=”, [“pitch”], 60]);

// Set the elevated layer to show at pitch > 60
map.setFilter(“natural-point-label-elevated”, [“>”, [“pitch”], 60]);

When combined, the pitch and distance-from-center expressions, alleviate the effect of perspective foreshortening, a phenomenon in which objects in the distance appear closer together. Distance thresholds, as in this example, prevent large labels from being clumped together.

[case,
  // At a low pitch always show labels
  ['<', ['pitch'], 60], true,
  // At a high pitch, only show labels close to the center
  ['all', ['>=', ['pitch'], 60], 
          ['<=', ['distance-from-center'], 2.0]
  ], true,
  // At a high pitch, hide labels far from the center
  false
]

Use these new expressions when styling with Mapbox Studio, or with the runtime API to set a filter.

Label Stability and Legibility improvements

Stable text placement with good legibility is critical for effective, distraction-free data visualization. Label orientation is now more stable when text is nearly vertical, as when following a long, straight road. We’ve made this and a number of other improvements to labels which customers can start using today with no changes to their code.

CJK Improvements

Latin and numeric characters in line labels previously did not match the orientation of CJK characters, causing users to have to switch reading direction for each character. Horizontal and vertical text-writing-mode, previously only enabled for point labels, is now available for line labels as well. This capability better meets the needs of users around the world.

To use this change, add the text-writing-mode property to line labels and specify which of horizontal and vertical modes to enable. 

{
  "id": "road-label",
  "type": "symbol",
  "source": "mapbox",
  "layout": {
  	"text-field": "{name}",
		"symbol-placement": "line",
    "text-writing-mode": ["horizontal", “vertical”],
    "text-rotation-alignment" : "map"  
	}
}

Documentation and Learning

We’ve overhauled the API reference documentation, migrating over a hundred examples to modern Javascript ES6 and closing hundreds of documentation issues reported by developers. We restructured the reference to group methods and events into named sections to make it easier for new developers to see GL JS capabilities at-a-glance. These improvements to the documentation make it easier for everyone to understand and build with the powerful features of the Mapbox GL JS library.

Start building with v2.6

With this release and those over the past summer, we continue to break new ground for interactive maps and make it easy to integrate with web applications. We've built top community requested features: adaptive projections, gesture handling (1, 2), and quickly resolved browser compatibility issues(1). To update to GL JS v2.6, include the following code in the <head> block of your HTML file:

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

See the release notes for a full list of changes.