Display a Globe with a Vector Map in Maptoolkit Maps JS
Switching to globe projection in Maptoolkit Maps JS is done by passing projection: ‘globe’ to the map constructor or by calling map.setProjection(‘globe’) at runtime. At higher zoom levels the map transitions back to Mercator automatically for accurate local rendering. Use the globe projection for world-scale overviews, satellite-like UIs, or any application where showing the curvature of the Earth adds visual context.
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
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 maptoolkit.NavigationControl(), 'top-right');
map.on('style.load', () => {
map.setProjection({ type: 'globe' });
});<!DOCTYPE html>
<html lang="en">
<head>
<title>Display a Globe with a Vector Map - Maptoolkit Maps JS</title>
<meta property="og:description" content="Render the map as a globe using the globe projection." />
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@maptoolkit/maps@11.0.0-beta.3/dist/maptoolkit.css" />
<style>
html, body { width: 100%; height: 100%; margin: 0; padding: 0; }
#map { width: 100%; height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
const API_KEY = 'YOUR_API_KEY';
const map = new maptoolkit.Map({
container: 'map',
apiKey: API_KEY,
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 maptoolkit.NavigationControl(), 'top-right');
map.on('style.load', () => {
map.setProjection({ type: 'globe' });
});
</script>
</body>
</html>Use the prompt below with any LLM to get the same result. Make sure the Maptoolkit MCP server is connected first — check out AI Integration & MCP to get started.
How it works
map.setProjection({ type: 'globe' }) switches the map from Web Mercator to a sphere. The
same style, the same tiles and the same layers are reprojected; nothing about the data
changes.
It is called inside map.on('style.load') rather than load. The projection applies to a
style, so the style has to exist first. You can also pass projection: 'globe' to the
constructor if the map should start as a globe.
zoom: 2 is deliberate. Globe projection only differs visibly from Mercator when zoomed out
far enough to see curvature; past roughly zoom 6 the two converge and the globe stops being
worth the cost.
The practical gain is at high latitudes: Mercator inflates Greenland and Antarctica badly, and a globe does not.
Next steps
A globe is worth building when the data is global, so the next step is usually plotting something that spans continents: flight paths, shipping routes, a worldwide customer map. Great-circle lines in particular look wrong on Mercator and correct on a sphere, which is much of the reason to use one.
It is also worth understanding the transition. Globe reads well zoomed out and stops earning its cost around zoom 6, which is where the projection hands over to Mercator on its own.