Display a Globe with an Atmosphere in MapLibre GL JS

MapLibre GL JS draws the atmosphere of a globe from the style’s sky. Calling map.setSky() with an atmosphere-blend value controls the halo around the sphere and how it fades as you zoom in. The space around the globe is the page behind the map, so a dark background turns it into night sky. Use this for an overview globe, a geopolitical visualization, or any map where a full-planet view is part of the experience.

const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
        container: 'map',
        style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
        center: [13.0, 47.5],
        zoom: 2,
        attributionControl: { compact: false }
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');

    map.on('style.load', () => {
        map.setProjection({ type: 'globe' });
        map.setSky({
            // The halo around the globe: full strength when zoomed out, fading out by zoom 7.
            'atmosphere-blend': ['interpolate', ['linear'], ['zoom'], 0, 1, 5, 1, 7, 0]
        });
    });

import { LogoControl } from "https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.js";
    map.addControl(new LogoControl({ variant: "com" }));

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Display a Globe with an Atmosphere - MapLibre GL JS</title>
    <meta property="og:description" content="Render a globe with an atmospheric sky effect using fog." />
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.1/dist/maplibre-gl.js"></script>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.1/dist/maplibre-gl.css" />
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.css" />
    <style>
        html, body { width: 100%; height: 100%; margin: 0; padding: 0; background: #111; }
        /* The globe is drawn on a transparent canvas, so this is the colour of space. */
        #map { width: 100%; height: 100%; background: #0b0b19; }
    </style>
</head>
<body>
<div id="map"></div>
<script>
    const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
        container: 'map',
        style: `https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=${API_KEY}`,
        center: [13.0, 47.5],
        zoom: 2,
        attributionControl: { compact: false }
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');

    map.on('style.load', () => {
        map.setProjection({ type: 'globe' });
        map.setSky({
            // The halo around the globe: full strength when zoomed out, fading out by zoom 7.
            'atmosphere-blend': ['interpolate', ['linear'], ['zoom'], 0, 1, 5, 1, 7, 0]
        });
    });
</script>
<script type="module">
    import { LogoControl } from "https://cdn.jsdelivr.net/npm/@maptoolkit/maplibre-logo-control@1.1.2/dist/maplibre-logo-control.js";
    map.addControl(new LogoControl({ variant: "com" }));
</script>
</body>
</html>

How it works

setSky sets the style’s sky. On a globe, the property that shows is atmosphere-blend: 1 draws the halo around the sphere at full strength and 0 switches it off. The expression keeps it at full strength up to zoom 5 and fades it out by zoom 7, because close up the globe fills the screen and a halo only gets in the way.

The sky specification also has colours: sky-color, horizon-color, fog-color and their -blend values. They colour the sky and the haze on a flat, tilted map. On the globe they make no visible difference, even tilted towards the horizon, so this example leaves them out.

Space is the page, not the style. MapLibre draws the globe on a transparent canvas, so what you see around the sphere is the background of the map container, set in CSS here. The sky specification has no space-color or star field.

setProjection and setSky are both called in style.load, because both belong to the style and are reset when a new one loads.

Not setFog. setFog, with space-color, star-intensity and high-color, is the Mapbox GL JS API. MapLibre GL JS has no setFog: the call throws map.setFog is not a function and nothing changes. Code ported from Mapbox needs setSky instead.

The Maptoolkit styles already ship a sky block with an atmosphere, so a globe gets a halo even without this call; setSky replaces it with your values.

Next steps

Change the zoom stops in atmosphere-blend to keep the halo longer as you zoom in, or set it to 0 to compare the globe without it.

Once the sphere looks right, the point is what you put on it. Global data is what justifies the projection, and an atmosphere over an empty globe is a screensaver rather than a map.