All docsMapbox GL JSGuidesGlobe and Atmosphere

Globe and Atmosphere

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

Use Globe in Mapbox GL JS

Change your map to a 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 as mentioned below). See examples for getting started, custom atmosphere styling, or rotating globe.

Atmosphere styling

By default, the area behind the globe will be transparent. You can add stars and an atmosphere with the fog property. To set the default atmosphere:

map.on('style.load', () => {
    map.setFog({});
});

Or for a custom atmosphere:

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.

Mapbox GL JS will also read the fog property from a map style, which can be customized 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.

Limitations of Globe

Globe has limited support for the following bounds-related APIs:

These API calls may not behave as expected, especially near the poles. We will address this in a future release.

Globe does not yet support CustomLayerInterface.

Globe does not support the deprecated sky layer. We recommend styling the sky and atmosphere with the fog property as described above.

Panning is limited by the poles. In the case where it's important to position the map center at pole, consider a polar projection.