Globe Projection with MapLibre GL JS
MapLibre GL JSDisplay the map as a 3D globe with atmosphere effects using MapLibre GL JS setProjection API.
const map = new maplibregl.Map({
container: 'map',
style: 'https://api.maptiler.com/maps/satellite/style.json?key=YOUR_MAPTILER_KEY',
center: [0, 20],
zoom: 1.2
});
map.addControl(new maplibregl.NavigationControl());
map.on('style.load', () => {
map.setProjection({ type: 'globe' });
});How it works
MapLibre GL JS supports globe projection through the setProjection() method. When using an external style URL (like MapTiler styles), call map.setProjection({ type: 'globe' }) after the style.load event fires. This ensures the style is fully loaded before the projection is changed.
The globe projection renders the map as a sphere at low zoom levels. As users zoom in past level 5-6, MapLibre transitions from the curved globe view to a flat Mercator projection. The satellite basemap works particularly well for globe visualization.
To add atmosphere effects, define a sky property in the style with atmosphere-blend: this creates a subtle glow at the globe edges. You can also toggle back to flat Mercator at runtime with map.setProjection({ type: 'mercator' }).
Key APIs
| API | Description | Docs |
|---|---|---|
map.setProjection() |
Switch between globe and mercator | maplibre.org docs |
style.load event |
Fires when external style is ready | maplibre.org docs |
sky style property |
Atmosphere/sky configuration | maplibre.org style spec |
FAQ
Why not set projection in the constructor?
When using an external style URL, the projection must be set after the style loads. Setting projection: 'globe' in the constructor only works with inline style objects, not URLs.
Can I use globe with 3D terrain?
Yes. Globe projection and terrain DEM work together. Add terrain as usual inside the style.load event.
Does globe projection affect performance?
Globe rendering adds minimal overhead. The transition from globe to Mercator happens automatically at higher zoom levels where the curvature becomes negligible.
Common mistakes
- Setting
projection: 'globe'in the constructor with an external style URL: it will be ignored; usesetProjection()afterstyle.load - Using the
loadevent instead ofstyle.load:setProjectionneeds the style to be parsed, whichstyle.loadguarantees - Forgetting to pass an object
{ type: 'globe' }: the string form'globe'may not work in all versions
Build maps using MapLibre GL JS with AI
Generate code like this globe projection with maplibre gl js example using the MapLibre GL JS skill in your IDE.
Related Examples
- Initialize a MapLibre GL JS Map
- 3D Terrain with MapLibre GL JS
- See how to do this in MapTiler SDK