Cobejs Globe

cobe.js Globe

When to Use

• Displaying an interactive rotating globe on a landing page or dashboard.
• Showing geographic data points (offices, users, servers) as markers on a 3D globe.
• Needing a lightweight (~5 KB) alternative to full Three.js globe solutions.
• Building "where we operate" or "global presence" sections.

Key Concepts

What Is cobe.js

cobe is a tiny WebGL globe renderer. It draws a dotted globe on a <canvas> element with smooth auto-rotation, configurable markers, and mouse/touch drag interaction — all in roughly 5 KB gzipped.

Installation

npm install cobe

Or via CDN:

<script src="https://unpkg.com/cobe"></script>

Core API

import createGlobe from "cobe";

const globe = createGlobe(canvasElement, {
  devicePixelRatio: 2,
  width: 600, // logical width (canvas is sized to width × devicePixelRatio)
  height: 600,
  phi: 0, // initial horizontal rotation (radians)
  theta: 0.3, // initial vertical tilt (radians)
  dark: 1, // 0 = light mode, 1 = dark mode
  diffuse: 1.2, // surface shading intensity
  mapSamples: 16000, // number of dots on the globe surface
  mapBrightness: 6, // brightness of land dots
  baseColor: [0.3, 0.3, 0.3], // RGB (0–1) for ocean/base
  markerColor: [0.1, 0.8, 1], // RGB (0–1) for markers
  glowColor: [0.05, 0.05, 0.2], // RGB (0–1) for atmospheric glow
  markers: [
    { location: [37.7749, -122.4194], size: 0.06 }, // San Francisco
    { location: [51.5074, -0.1278], size: 0.06 }, // London
    { location: [35.6762, 139.6503], size: 0.04 }, // Tokyo
  ],
  onRender: (state) => {
    // Called every frame — use to animate rotation
    state.phi += 0.005;
  },
});

Configuration Options

Markers

Each marker is defined by a geographic coordinate and a size:

markers: [
  { location: [40.7128, -74.006], size: 0.08 }, // New York
  { location: [48.8566, 2.3522], size: 0.06 }, // Paris
  { location: [-33.8688, 151.2093], size: 0.05 }, // Sydney
];

• location is [latitude, longitude] in decimal degrees.
• size controls the marker radius relative to the globe (0.03–0.1 is typical).

Auto-Rotation

Animate rotation inside the onRender callback:

onRender: (state) => {
  state.phi += 0.003; // horizontal rotation speed
};

To pause rotation on hover or drag, track a flag:

let pointerDown = false;
canvas.addEventListener("pointerdown", () => (pointerDown = true));
canvas.addEventListener("pointerup", () => (pointerDown = false));

onRender: (state) => {
  if (!pointerDown) {
    state.phi += 0.003;
  }
};

Cleanup

createGlobe() returns a destroy function:

const globe = createGlobe(canvas, {
  /* options */
});

// When done:
globe.destroy();

Always call destroy() when removing the globe (SPA route change, component unmount).

Quick Recipes

Interactive Globe with Markers

<canvas
  id="globe-canvas"
  style="width: 600px; height: 600px; max-width: 100%; aspect-ratio: 1;"
></canvas>

<script type="module">
  import createGlobe from "cobe";

  const canvas = document.getElementById("globe-canvas");

  let phi = 0;

  const globe = createGlobe(canvas, {
    devicePixelRatio: Math.min(window.devicePixelRatio, 2),
    width: canvas.offsetWidth * 2,
    height: canvas.offsetWidth * 2,
    phi: 0,
    theta: 0.25,
    dark: 1,
    diffuse: 1.2,
    mapSamples: 16000,
    mapBrightness: 6,
    baseColor: [0.15, 0.15, 0.2],
    markerColor: [0.39, 0.4, 0.95], // indigo-ish
    glowColor: [0.08, 0.08, 0.15],
    markers: [
      { location: [37.7749, -122.4194], size: 0.06 }, // San Francisco
      { location: [51.5074, -0.1278], size: 0.06 }, // London
      { location: [35.6762, 139.6503], size: 0.05 }, // Tokyo
      { location: [1.3521, 103.8198], size: 0.04 }, // Singapore
      { location: [-23.5505, -46.6333], size: 0.05 }, // Sao Paulo
      { location: [30.0444, 31.2357], size: 0.05 }, // Cairo
    ],
    onRender: (state) => {
      state.phi = phi;
      phi += 0.003;
    },
  });

  // Cleanup on page unload
  window.addEventListener("beforeunload", () => globe.destroy());
</script>

Responsive Globe

function createResponsiveGlobe(canvas, markers) {
  let globe;
  let phi = 0;

  function init() {
    const width = canvas.offsetWidth;
    const dpr = Math.min(window.devicePixelRatio, 2);

    if (globe) globe.destroy();

    globe = createGlobe(canvas, {
      devicePixelRatio: dpr,
      width: width * dpr,
      height: width * dpr,
      phi: phi,
      theta: 0.2,
      dark: 1,
      diffuse: 1.2,
      mapSamples: width < 400 ? 8000 : 16000, // fewer dots on small screens
      mapBrightness: 6,
      baseColor: [0.2, 0.2, 0.25],
      markerColor: [0.4, 0.8, 1],
      glowColor: [0.05, 0.05, 0.15],
      markers: markers,
      onRender: (state) => {
        state.phi = phi;
        phi += 0.003;
      },
    });
  }

  init();

  const resizeObserver = new ResizeObserver(() => init());
  resizeObserver.observe(canvas);

  return {
    destroy() {
      resizeObserver.disconnect();
      if (globe) globe.destroy();
    },
  };
}

React Component

import { useEffect, useRef } from "react";
import createGlobe from "cobe";

export default function Globe({ markers = [], className }) {
  const canvasRef = useRef(null);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;

    let phi = 0;
    const width = canvas.offsetWidth;
    const dpr = Math.min(window.devicePixelRatio, 2);

    canvas.width = width * dpr;
    canvas.height = width * dpr;

    const globe = createGlobe(canvas, {
      devicePixelRatio: dpr,
      width: width * dpr,
      height: width * dpr,
      phi: 0,
      theta: 0.25,
      dark: 1,
      diffuse: 1.2,
      mapSamples: 16000,
      mapBrightness: 6,
      baseColor: [0.15, 0.15, 0.2],
      markerColor: [0.39, 0.4, 0.95],
      glowColor: [0.08, 0.08, 0.15],
      markers,
      onRender: (state) => {
        state.phi = phi;
        phi += 0.003;
      },
    });

    return () => globe.destroy();
  }, [markers]);

  return (
    <canvas
      ref={canvasRef}
      className={className}
      style={{ width: "100%", maxWidth: 600, aspectRatio: "1" }}
    />
  );
}

Usage:

<Globe
  markers={[
    { location: [37.77, -122.42], size: 0.06 },
    { location: [51.51, -0.13], size: 0.06 },
  ]}
  className="mx-auto"
/>

Common Pitfalls

Best Practices

1. Cap devicePixelRatio at 2. Values above 2 quadruple pixel count with negligible visual benefit.
2. Use mapSamples wisely. 16000 looks good on desktop; reduce to 8000–10000 on mobile for smoother frame rates.
3. Track phi outside the globe instance. This allows seamless rotation continuity across resizes or re-renders.
4. Match colors to your design system. Convert hex colors to normalized RGB ([r/255, g/255, b/255]).
5. Lazy-load cobe. The globe is rarely above the fold — dynamically import it when the section scrolls into view:

   const { default: createGlobe } = await import("cobe");
   

6. Respect reduced motion:

   const reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
   onRender: (state) => {
     if (!reduced) state.phi += 0.003;
   };
   

7. Use ResizeObserver instead of window.resize for responsive re-initialization — it fires only when the actual container changes size.
8. Keep marker sizes proportional. Sizes between 0.03 and 0.1 work best. Larger markers overlap and become unreadable.