I built an interactive globe without WebGL or map tiles

Harsh Jhunjhunuwala — Tue, 15 Sep 2026 03:30:00 +0000

The requirement sounded small: put an interactive globe on a web page.

I wanted people to drag it, zoom it, hover over countries, place markers, and show routes between locations. I also wanted it to fit naturally inside dashboards, launch pages, status boards, and visual reports.

When I explored the available options, I kept finding tools built for a bigger job. Some focused on advanced 3D effects. Others were complete mapping platforms. Both are useful, but I did not want every project to set up a map provider, load map tiles, or create an entire 3D scene just to show a focused globe visual.

So I wrote down a few rules for my own library:

it should use the browser's regular 2D canvas;
it should not need a map API key;
it should not make required network requests while running;
it should have no runtime dependencies; and
the same data should work on a globe and on a flat world map.

That project became CanvasGlobe.

The public API ended up being fairly small. The surprising part was how many visual problems were hiding behind that simple circle.

Drawing a circle was the easy part

The globe uses an orthographic projection. In plain language, it shows one half of Earth as if you were looking at it from very far away. This creates the familiar round globe shape without needing a 3D engine.

For each location, the library calculates three things:

its horizontal position;
its vertical position; and
whether it is on the front or back of the globe.

That last answer is what makes the flat canvas feel three-dimensional. A marker on the back should disappear. A route should travel behind the globe instead of showing through it. Countries near the edge should gradually leave the visible side.

The browser is still drawing pixels on a 2D canvas. The sense of depth comes from hiding the right things, changing their size, adding shading, and moving everything consistently when the globe rotates.

The first version fell apart at the edge

At first, hiding points on the back sounded sufficient. It worked for markers, but countries are not single points. A country near the edge of the globe can be partly visible and partly hidden.

If I simply removed the hidden part, the country shape was left open. Filled areas could flicker or draw strange lines across the globe while it moved.

The solution was to find the exact places where a country's outline crosses the visible edge. The library draws the visible part, follows the circular edge of the globe across the hidden gap, and then continues when the country comes back into view.

This small detail made a large visual difference. Before it, the result looked like a flat map placed inside a round mask. After it, countries appeared to move naturally around a sphere.

Routes could not just be straight lines

The next feature I wanted was a route between two cities.

Drawing a straight line between their longitude and latitude values works in a few cases, but it is not how the shortest route across a globe behaves. It also produces awkward results when a route crosses from one side of the world map to the other.

Instead, CanvasGlobe calculates points along the surface of a sphere. This is commonly called a great-circle route. It is why long-distance flight paths often look curved on a flat map.

The same route data can then be shown in two ways. On the globe, the hidden section passes behind the Earth. On a flat map, the path follows the selected map view.

I liked this part of the design because the feature is not tied to one visual style. A user can switch between the globe and map without rebuilding the route data.

The flat map had its own edge problem

The globe naturally hides half of the world. A flat map has to decide where the world begins and ends.

That boundary is usually placed near 180 degrees longitude, on the opposite side of the world from the main map center. It is known as the antimeridian.

A country outline may contain one point at longitude 179 and the next at -179. Those points are actually close together, but a simple drawing command sees them on opposite sides of the canvas and draws a line across the entire map.

CanvasGlobe detects that jump and starts a new section of the outline. When the map is zoomed and moved, it also shifts the world boundary away from the current view when possible.

The globe and the flat map now share the same geographic data, but they handle their edges differently. Trying to force one drawing method onto both made the code look simpler and the map look worse, so I kept the two paths separate.

Hovering meant working backwards

Drawing answers one question: where should a country appear on the canvas?

Hovering asks the reverse: which country is under this pixel?

The library first converts the pointer position back into a geographic location. A pointer outside the round globe can be rejected immediately. It then ignores countries whose broad boundaries are nowhere near that location and checks the remaining shapes more carefully.

Markers use a simpler check. Their screen positions and clickable sizes are remembered during drawing, so the library only needs to measure the distance from the pointer.

Keeping these two checks separate made everyday marker interaction fast without sacrificing country hover and click behavior.

An idle globe should be quiet

Canvas does not remember objects like regular HTML does. When something changes, the scene must be drawn again.

The easiest approach is to repaint on every screen refresh. That also wastes work when the globe is sitting still.

CanvasGlobe keeps track of whether something actually changed and whether anything is still moving. It continues drawing during a drag, a smooth move to another location, automatic rotation, animated routes, or live effects. When the scene is idle, it avoids repainting the same frame.

The drawing rate can also be limited. A decorative dashboard globe may not need to run at the highest rate a display supports.

For the dotted-land theme, the library does another piece of work only once. It creates a small hidden picture of the land and uses that picture to decide which dots belong on countries. This is much cheaper than repeatedly checking every dot against every country outline.

None of these changes is dramatic alone. Together, they help the library stay reasonable on pages where the globe is one component among many.

Mouse support was not enough

It was easy to make the globe pleasant with a mouse and still leave out people using a keyboard or reduced-motion settings.

When interaction is enabled, the canvas can receive keyboard focus. Arrow keys rotate the view, plus and minus zoom, and 0 resets it. Page Up and Page Down move between markers, while Enter or Space activates the selected marker.

The library also listens to the browser's reduced-motion preference. If a user has asked for less motion, automatic rotation and non-essential animation are suppressed while direct controls continue to work.

There is still an important limit here. Useful data should not exist only as pixels. A dashboard should provide a nearby table, summary, or another readable HTML view when people need the actual values.

The same canvas could create the marketing assets

I did not want one renderer for the live product and another for screenshots and social graphics.

CanvasGlobe can draw the current scene onto a temporary canvas at a different size. That makes it possible to export square images, story images, Open Graph graphics, LinkedIn images, or transparent PNG files without resizing the globe people are currently using.

For short video clips, it uses the browser's built-in canvas recording support. The frames are recorded and combined inside the tab, then returned as a downloadable file. Nothing has to be uploaded to a CanvasGlobe server.

Video format support still differs between browsers, so image export remains the dependable fallback.

What I chose not to build

Using Canvas 2D solved the problem I had, but it also gave the project a clear boundary.

CanvasGlobe is not the right choice for terrain, elevation, buildings, custom 3D models, street maps, advanced lighting, or thousands of separate objects in 3D space.

For those jobs, I would look at:

Cobe for a polished visual globe;
globe.gl for richer 3D globe layers;
MapLibre GL JS for interactive maps built from map tiles; or
CesiumJS for a complete 3D geographic platform.

I was not trying to replace those tools. I wanted to cover the space between a static globe illustration and a full mapping engine.

Try it

Install the package:

npm install canvas-globe

Add a canvas to the page:

<canvas id="globe" style="width: min(100%, 560px); aspect-ratio: 1"></canvas>

Then create a globe:

import { createGlobe } from "canvas-globe";

const globe = createGlobe(document.querySelector("#globe"), {
  theme: "atlas",
  markers: [
    { lat: 23.03, lon: 72.58, count: 12, city: "Ahmedabad" },
    { lat: 51.50, lon: -0.12, count: 8, city: "London" },
  ],
  arcs: [
    { from: [72.58, 23.03], to: [-0.12, 51.50] },
  ],
  tooltip: (marker) => `${marker.city}: ${marker.count}`,
  onClick: (marker) => globe.flyTo(marker.lon, marker.lat, { zoom: 2.5 }),
});

You can explore the working project here:

CanvasGlobe is available under GPL-3.0-only for projects that comply with GPLv3. If you are distributing it in a proprietary product, you must purchase a commercial license. See the commercial plans and pricing.

The library is still early. If you try it, I would genuinely like to know where the API feels awkward, how it behaves on lower-end mobile devices, and which real-world globe use cases are still missing.

Disclosure: I am the author and licensor of CanvasGlobe.

DEV Community: Harsh Jhunjhunuwala