# globe.gl: a web component for putting data on a spinning sphere

> A thin web component that wraps the three-globe plugin so you can render arcs, polygons, hexes, heatmaps and HTML markers on a WebGL globe. Good fit for dashboards and newsroom graphics, weak fit for anything needing map tiles.

**vasturiano/globe.gl** — UI component for Globe Data Visualization using ThreeJS/WebGL

- Repository: https://github.com/vasturiano/globe.gl
- Website: https://vasturiano.github.io/globe.gl/example/world-population/
- Stars: 3,190 · Forks: 434
- Language: HTML
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/vasturiano-globe-gl

## What it is: a component around another component

The README is precise about the layering, and getting this right saves you from looking in the wrong repository. Globe.GL is a web component for data visualization layers on a three-dimensional globe in a spherical projection. It is a convenience wrapper around the `three-globe` plugin, and it uses ThreeJS and WebGL for the actual rendering.

So the questions split in two. How do I get a globe on my page, with custom elements and attributes, that is this repository. What exactly is drawn on the globe, including the quadtree and the data layer implementations, is `three-globe`. Both are by the same author, and the dependency range pins `three-globe` at `^2.45` while `three` is held to `>=0.179 <1`.

The package manifest gives the rest of the shape. Version is 2.46.2, the module type is ESM, distribution goes through `dist/globe.gl.mjs` with a UMD build at `dist/globe.gl.min.js` and TypeScript declarations at `dist/globe.gl.d.ts`. There are no GitHub releases, so the npm version is the version to track. The last push was on 2026-08-22, and the project is not archived.

## Building the library from the repository

The published package is the normal route. If you want the source, the tree is small and conventional: a `src/` directory, a `rollup.config.js` for the production bundle, a `rollup.config.dev.js` for the watch build, `example/` holding every demo page, and `yarn.lock`.

```bash
npm install
npm run dev
```

The production build is a single script, and it cleans the output directory first:

```bash
npm run build
```

That maps to `rimraf dist && rollup -c` in the package scripts. The dev script is `rollup -w -c rollup.config.dev.js`, so a watch build. TypeScript support is not incidental: `@typescript/typescript6` and `rollup-plugin-dts` are dev dependencies, which is where the `.d.ts` file in the exports map comes from.

One packaging detail tells you how the library expects to be consumed. The `sideEffects` array lists `./src/*.css`, so the stylesheet is treated as having side effects while the JavaScript does not. That matters if you tree-shake aggressively and find your globe unstyled.

## The example list is the real API documentation

There is no API reference in this repository, which is unusual and initially confusing. What replaces it is a long list of named examples, each linking to a live page and to its `index.html` source. The list reads like a catalogue of visual forms: Basic, Arc Links, Highlight links, Choropleth, Elevated Polygons, Hollow Globe, Day/Night Cycle, Path Lines, Heatmap, Map Labels, HTML Markers, Hexed Country Polygons, Tiles, Ripple Rings, Emit Arcs on Click, Clouds, Solar Terminator, Tiled Map Engine, Custom Globe Styling, Custom Layer, World Population, Population Heatmap, Recent Earthquakes and World Volcanoes.

Reading that list tells you what the library considers its core job. Arcs, paths, rings, hexes, heatmaps and custom layers are the drawing primitives. Tiles, day/night cycle, clouds and solar terminator are the texture-and-light features that make the globe look like Earth rather than a ball.

The dashboard pages are built on GitHub Pages, with `CNAME` and `_config.yml` in the tree, and the package homepage points at a world population example. The author's related projects are named in the README too: an AR version and a set of React bindings, so if you are in React, reach for those rather than wrapping the custom element yourself.

## Where the design decisions actually live

The dependency list is short and tells you the architectural choices. `kapsule` is the capsule library that provides the component's encapsulated reactive state, which is how the web component tracks its props and emits updates. `accessor-fn` handles the accessor pattern used throughout the ThreeJS ecosystem, letting you pass a function where a plain value would normally work.

```json
"dependencies": {
  "@tweenjs/tween.js": "18 - 25",
  "accessor-fn": "1",
  "kapsule": "^1.16",
  "three": ">=0.179 <1",
  "three-globe": "^2.45",
  "three-render-objects": "^1.41"
}
```

`three-render-objects` is the layer underneath `three-globe`, handling the batching and culling of many objects as a single draw call. That is the reason a globe can carry tens of thousands of points without falling over, and it is also why the ThreeJS version range matters so much: these packages are tightly coupled to ThreeJS internals rather than to a stable public API.

Animation runs through `@tweenjs/tween.js`, with a deliberately wide range of `18 - 25`. Camera moves and arc draws are tweened rather than hand-rolled, which is a reasonable division of labour if you are used to it and one more thing to understand if you are not.

## Where a globe is the wrong tool

A spherical projection is a strong aesthetic and a weak coordinate system. Globe.GL is built for showing relationships across the whole planet: arcs between cities, a choropleth of country values, a heatmap of population density. It is built badly for showing one region in detail, because zooming a globe does not reveal street-level labels, and text placed on a sphere is either curved or floating and hard to read at any size.

The Tiles and Tiled Map Engine examples exist, so the library is not ignorant of map data, and it does render raster tiles onto the sphere. If your requirement is pan, zoom and readable place names over a country, a dedicated map library with vector tiles will do the job with less fight, because that is what it was designed for and the tile pipeline is not something a sphere component rebuilds.

Performance is the second limit. Everything is WebGL, so the ceiling is your GPU and your data volume. The batching in `three-render-objects` buys you a lot of headroom, but a heatmap layer at high resolution combined with clouds and a day/night texture is still several full-screen passes per frame, and on integrated graphics or a laptop that runs down to a battery it shows.

The third limit is browser support, and the README is quiet about it. WebGL is the floor, so a device or browser without WebGL gets nothing, and there is no fallback described anywhere in the documentation.

## Conclusion

globe.gl earns its keep when the shape of your data is inherently global, since arcs between two points, elevated polygons and hex grids are the visual forms a 2D map handles badly, and the same file can render them without a mapping library. It is the wrong choice for anything that needs readable local detail, labels at street level or pan-and-zoom over a region, because a spherical projection with a texture is a different tool from a tile map. Note the layering: the rendering work lives in three-globe and this repository is the web component and build around it, so version compatibility follows ThreeJS releases. Start with the Basic example, then move to Arc Links and Choropleth, and check that `three-globe` is at least version 2.45 before you upgrade ThreeJS.

## FAQ

### What is globe.gl?

It is a web component that renders data visualization layers on a three-dimensional globe in a spherical projection, using ThreeJS and WebGL. It is a convenience wrapper around the author's `three-globe` plugin, which does the actual rendering work.

### Does globe.gl work with React?

The README points to a separate set of React bindings maintained by the same author, so use those rather than wrapping the custom element yourself. The React package is a different repository, and the core library here is framework-agnostic.

### Can globe.gl render map tiles on the globe?

Yes. There are Tiles and Tiled Map Engine examples in the repository for rendering raster tiles onto the sphere. If you need pan, zoom and readable labels over a single region rather than global relationships, a dedicated tile map library is the better fit.

### What ThreeJS version does globe.gl require?

The package manifest pins `three` to `>=0.179 <1` and `three-globe` to `^2.45`, so upgrading ThreeJS past a major version will likely break the integration. The ecosystem packages the library depends on reach into ThreeJS internals rather than only its public API.

## Sources

- [Issues](https://github.com/vasturiano/globe.gl/issues)
- [License: MIT](https://github.com/vasturiano/globe.gl/blob/master/LICENSE)
- [Project website](https://vasturiano.github.io/globe.gl/example/world-population/)
- [README](https://github.com/vasturiano/globe.gl/blob/master/README.md)
- [vasturiano/globe.gl on GitHub](https://github.com/vasturiano/globe.gl)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vasturiano-globe-gl