Skip to main content

Your first globe

One canvas, one call​

createGlobe takes a <canvas> and an options object. That is the entire setup.

<canvas id="globe" style="width: 480px; aspect-ratio: 1"></canvas>
import { createGlobe } from "canvas-globe";

const globe = createGlobe(document.querySelector("#globe"), {
  licenseKey: "your_license_key",
  markers: [{ lat: 23.03, lon: 72.58, count: 12, emoji: "🧑‍🎨", live: true }],
});

Commercial customers receive a key with their order. GPLv3-compatible projects can request a complimentary key.

Loading globe…

:::warning Size the canvas with CSS, not attributes Give the element a width and an aspect-ratio in CSS. CanvasGlobe reads the rendered size, sets the backing store for the device pixel ratio, and re-reads it whenever the element resizes. Setting width="480" as an HTML attribute will look blurry on retina screens. :::

Add some data​

A marker needs lat and lon. Everything else is optional and comes straight back to your callbacks, so you can hang whatever you like on it.

const globe = createGlobe(canvas, {
  markers: [
    { lat: 23.03, lon: 72.58, count: 12, emoji: "🧑‍🎨", live: true, city: "Ahmedabad" },
    { lat: 51.5, lon: -0.12, count: 8, emoji: "👩‍💻", city: "London" },
    { lat: 40.71, lon: -74.01, count: 6, emoji: "🧑‍🚀", city: "New York" },
  ],
  tooltip: (m) => `${m.city}: ${m.count} people`,
  onClick: (m) => globe.flyTo(m.lon, m.lat, { zoom: 2.5 }),
});
Loading globe…

Switch to a flat map​

Same instance, same markers: one option.

Loading globe…

Drive it afterwards​

Every method returns the instance, so calls chain.

globe
  .setMarkers(next)
  .setTheme("midnight")
  .flyTo(139.69, 35.68, { zoom: 3 });

Clean up​

If your framework unmounts the canvas, destroy the instance. It cancels the animation frame, removes listeners, and releases the tooltip, live region and any media.

globe.destroy();

The React component and custom element do this for you.

Next​