globe.gl

globe.gl is a convenience wrapper around the three-globe library that renders points, arcs, polygons, paths, heatmaps, hex bins, tiles, particles, rings, labels, HTML markers, and custom 3D objects on an interactive, spherical Earth using Three.js and WebGL. It exposes a fluent, chainable API — construct a Globe instance against a DOM element, then configure layers of geospatial data with declarative accessor functions for color, altitude, size, and interaction behavior.

Built by Vasco Asturiano, the same author behind three-globe and three-render-objects, globe.gl bundles orbit controls, camera transitions, tooltips, and click/hover event handling out of the box. It also ships official React, Vue, and Angular bindings maintained as sibling packages, making it a common choice for dashboards, network/traffic visualizations, and any project that needs to plot geographic data on a rotating 3D Earth rather than a flat map.

What You Get

• A chainable Globe() component with 14+ visual layer types — points, arcs, polygons, paths, heatmaps, hex bins, hex polygons, tiles, particles, rings, labels, HTML elements, 3D objects, and custom layers
• Built-in orbit controls, an animated pointOfView() camera transition method, and coordinate-conversion utilities (toGeoCoords, getScreenCoords, toGlobeCoords)
• Click, right-click, and hover event handlers per layer type with customizable tooltip label accessors
• Bundled TypeScript declarations plus official framework bindings for React (react-globe.gl), Vue, and Angular
• UMD, ESM, and CDN (jsDelivr/unpkg) distribution builds for both bundler and script-tag usage

Common Use Cases

• Visualizing global network traffic, flight routes, or submarine cable maps as animated arcs between coordinates
• Rendering choropleth-style country or region data as colored, elevated polygons on a sphere
• Plotting geolocated events such as earthquakes, cities, or satellites as points, heatmaps, or hex-bin aggregates
• Building interactive product demos, dashboards, or marketing pages featuring a rotating, data-driven Earth

Under The Hood

Architecture globe.gl is a thin composition layer built on the Kapsule component-factory pattern (src/globe.js, ~656 lines): it instantiates a ThreeGlobe (from the sibling three-globe package) and a ThreeRenderObjects scene/camera/renderer wrapper, then uses a custom linkKapsule helper (src/kapsule-link.js) to auto-generate roughly 150 linked getter/setter props and methods that proxy straight through to the underlying ThreeGlobe instance’s own Kapsule-based API. All visual layers are actually implemented in three-globe; globe.gl’s own code is limited to wiring click/hover/tooltip dispatch (shared dataAccessors/hoverObjFns/clickObjFns lookup tables keyed by an internal __globeObjType tag), the animated pointOfView() camera tween (via @tweenjs/tween.js), and one-time orbit-control calibration (min/max distance, damping, zoom-to-cursor) performed in init(). A requestAnimationFrame loop (_animationCycle) ticks the renderer and the tween group each frame.

Tech Stack Distributed as pure ESM (type: module) with UMD/minified builds for CDN use, built via Rollup with Babel transpilation and a separate rollup-plugin-dts pass to bundle hand-written TypeScript declarations (src/index.d.ts). Runtime dependencies are all from the same author’s ecosystem: three-globe (^2.45) for the actual globe rendering, three-render-objects (^1.41) for the generic Three.js scene/camera/controls harness, kapsule (^1.16) for the component factory pattern, accessor-fn for value-or-function prop resolution, and @tweenjs/tween.js for camera animation; three itself is a wide peer-range dependency (>=0.179 <1). No test runner, linter, or CI workflow is configured in the repo.

Code Quality There is no test suite anywhere in the repository (no test/ or tests directory, no test script in package.json) — correctness is implicitly exercised through 30 runnable HTML examples under example/ covering every layer type. The single source file is dense but consistently organized: linked props/methods are declared by mapping over prop-name arrays rather than hand-written boilerplate, and per-layer event dispatch is centralized into small lookup-table objects rather than duplicated per-layer conditionals. Naming is consistent and self-descriptive across layers (onXClick, xLabel, xData), though the lack of inline commentary beyond section dividers and the absence of automated tests make internal correctness hard to verify from source alone.

API Design The public API is a single default export — new Globe(domElement, configOptions) — followed by chainable getter/setter methods (.pointsData(arr).pointColor(‘color’)…), applying the same convention across every layer, which makes the surface highly learnable once one layer is understood. Every accessor prop accepts a static value, a string key, or a function via accessor-fn, giving flexible declarative data-binding without imperative update code. Onboarding cost is low for basic usage (a script tag plus a few lines yields a working globe per the README quick-start), but the full prop surface is very large (~150 configuration properties), and discovering the right prop names leans on the lengthy README API-reference table rather than IDE-autocomplete-first ergonomics — partially offset by the bundled .d.ts types and by the official React/Vue/Angular wrapper packages, which translate this imperative Kapsule API into idiomatic declarative props for framework users.