Globe and Atmosphere | Mapbox GL JS

Mapbox GL JS supports displaying the map as a 3D globe, starting from v2.9.

Use Globe in Mapbox GL JS

Most of the latest Mapbox styles use globe by default. Using these styles or a style created them in Studio will enable globe on your map.

Navigation styles default to the Mercator projection.

You can change any other map to globe by setting the projection property.


const map = new mapboxgl.Map({
  container: 'map',
  projection: 'globe'
});

Globe is compatible with all tile sources and map styles (with a few caveats). See examples for custom atmosphere styling and rotating globe.

Atmosphere styling

The latest Mapbox styles include atmosphere by default. You can customize stars and atmosphere with the fog property. To set a custom atmosphere in GL JS:


map.on('style.load', () => {
  map.setFog({
    color: 'rgb(186, 210, 235)', // Lower atmosphere
    'high-color': 'rgb(36, 92, 223)', // Upper atmosphere
    'horizon-blend': 0.02, // Atmosphere thickness (default 0.2 at low zooms)
    'space-color': 'rgb(11, 11, 25)', // Background color
    'star-intensity': 0.6 // Background star brightness (default 0.35 at low zoooms )
  });
});

These properties support zoom expressions, for instance to fade from starry space at low zooms to a blue sky at high zooms.

Atmosphere can also be customized per-style in Mapbox Studio.

Behavior

For any camera zoom level and location, maps in globe will be rendered at roughly the same size. At low zoom levels, the same zoom level will result in features near the poles appearing larger in Mercator, while near the equator features will appear larger in globe. This is a compromise ensuring relatively consistent map appearance given the size distortion inherent in Mercator.