chlobe

Visualize country data on a glbe.

chlobe: a 15kb React globe, inspired by the brilliant cobe.

pnpm add @lachlanjc/chlobe

Freshwater withdrawals
per person

0 m³/person3,630 m³/person· square-root globe scale

Forest area per person

  • 8.66 haCanada
  • 5.67 haRussian Federation
  • 2.33 haBrazil
  • 1.16 haCongo, Dem. Rep.
  • 0.16 haChina
  • 0.05 haIndia
0 ha/person24.11 ha/person

Darker dots, more forest per person · logarithmic scale

Oil production

Less productionMore production

Globe: logarithmic color scale · bars: annual production

Selected producersAnnual production

Renewable electricity

0%100% renewable
Renewable electricityOther generation

The backstory

Most globes on the web use 3D renderers, which are massive. Shu Ding’s cobe realized you could prebuild a tiny bitmap of where land is and render a sphere with a shader in just 5kb. Brilliant!

But cobe doesn’t know where countries are. Adding GeoJSON data and rendering it is easily >100kb. chlobe evolves cobe’s approach, preprocessing the GeoJSON and uniquely coloring each country into the compressed bitmap, then keeping an index of country codes & colors to render levels over each country’s dots using a provided color scale. The library is just 15kb minified.

Thanks to Nick Rabinowitz for this idea.

Agents quickstart

Install cobe to visualize country data per https://raw.githubusercontent.com/lachlanjc/chlobe/refs/heads/main/README.md

Install & use

Requires React 18+ and WebGL:

pnpm add @lachlanjc/chlobe

Render a globe with an RGB color ramp (it’s more efficient for shaders):

globe.tsx
'use client';import { ChoroplethGlobe } from '@lachlanjc/chlobe';// Renewable electricity share (%), 2021.const data = [  { alpha2: 'NO', value: 99.1 },  { alpha2: 'BR', value: 77.4 },  { alpha2: 'DE', value: 39.8 },  { alpha2: 'CN', value: 28.4 },  { alpha2: 'SA', value: 0.1 },];<ChoroplethGlobe  aria-label="Example renewable electricity shares by country"  colors={{    filled: [[219, 234, 254], [29, 78, 216]],    missing: [148, 163, 184],    base: [255, 255, 255],    glow: [217, 217, 230],  }}  data={data}  autoRotate={true}  interactive={true}/>
Options

Custom legend

Hover or focus a legend button to highlight its country. Click it to rotate the globe there.

globe-legend.tsx
'use client';import { useRef } from 'react';import { ChoroplethGlobe, type ChoroplethGlobeRef } from '@lachlanjc/chlobe';// Renewable electricity share (%), 2021.const data = [  { alpha2: 'NO', value: 99.1 },  { alpha2: 'BR', value: 77.4 },  { alpha2: 'DE', value: 39.8 },  { alpha2: 'CN', value: 28.4 },  { alpha2: 'SA', value: 0.1 },];const countryNames = new Intl.DisplayNames(['en'], { type: 'region' });export const GlobeWithLegend = () => {  const globe = useRef<ChoroplethGlobeRef>(null);  return (    <>      <ChoroplethGlobe        aria-label="Custom legend globe preview"        ref={globe}        data={data}        autoRotate={true}        interactive={true}        colors={{          filled: [[219, 234, 254], [29, 78, 216]],          missing: [148, 163, 184],          base: [255, 255, 255],          glow: [217, 217, 230],        }}      />      {data.map(({ alpha2, value }) => (        <button          key={alpha2}          type="button"          onMouseEnter={() => globe.current?.setActiveEntry(alpha2)}          onMouseLeave={() => globe.current?.clearActiveEntry()}          onFocus={() => globe.current?.setActiveEntry(alpha2)}          onBlur={() => globe.current?.clearActiveEntry()}          onClick={() => globe.current?.navigateToEntry(alpha2)}        >          {countryNames.of(alpha2) ?? alpha2} · {value}%        </button>      ))}    </>  );};
Options

Custom tooltip

Hover a country to see its name and renewable electricity share. Countries outside the dataset show “No data”.

globe-tooltip.tsx
'use client';import { ChoroplethGlobe } from '@lachlanjc/chlobe';// Renewable electricity share (%), 2021.const data = [  { alpha2: 'NO', value: 99.1 },  { alpha2: 'BR', value: 77.4 },  { alpha2: 'DE', value: 39.8 },  { alpha2: 'CN', value: 28.4 },  { alpha2: 'SA', value: 0.1 },];const countryNames = new Intl.DisplayNames(['en'], { type: 'region' });<ChoroplethGlobe  aria-label="Country tooltip globe preview"  data={data}  colors={{    filled: [[219, 234, 254], [29, 78, 216]],    missing: [148, 163, 184],    base: [255, 255, 255],    glow: [217, 217, 230],  }}  autoRotate={true}  interactive={true}  formatValue={(value) => `${value}% renewable electricity`}  style={{ containerType: 'inline-size' }}  renderTooltip={({ alpha2, label, formattedValue, x, y }) => (    <div      role="tooltip"      style={{        position: 'absolute',        boxSizing: 'border-box',        top: 0,        left: 0,        transform: `translate(clamp(0px, ${x - 110}px, calc(100cqw - 220px)), calc(${y}px - 100% - 12px))`,        width: 'min(220px, 100%)',        overflowWrap: 'anywhere',        whiteSpace: 'normal',        pointerEvents: 'none',        background: '#ffffff',        color: '#354150',        border: '1px solid #cbd5e1',        borderRadius: 2,        boxShadow: '0 4px 16px rgb(15 23 42 / 0.12)',        fontSize: 13,        padding: '8px 10px',      }}    >      <strong>{label ?? countryNames.of(alpha2) ?? alpha2}</strong>      <span style={{ display: 'block' }}>        {formattedValue ?? 'No data'}      </span>    </div>  )}/>
Options

API reference

PropertyDefaultDescription
dataRequiredCountry entries: unique alpha2, value, optional id and label · IDs default to alpha2
colorsRequiredTwo filled RGB tuples and one missing tuple; channels 0–255
colors.missingAlpha0.25Missing-country opacity
colors.base / colors.glowColor schemeSurface and glow RGB tuples
colorSchemelightLight or dark shading and default surface and glow colors; custom colors override the defaults
sizeContainer widthSquare size in CSS pixels
autoRotatetrueIdle rotation
interactivetrueDragging, hover, and left/right arrows
initialPhi0Starting rotation in radians
activeEntryIdUncontrolledSelected ID; null clears · Pair with onActiveEntryChange
defaultActiveEntryIdnullInitial uncontrolled selection
onActiveEntryChangeRequested active ID or null from ref methods
onCountryHoverPointer country code or null; independent of selection
formatValueFormats (value, entry)
renderTooltipCustom tooltip UI; absent by default
aria-labelCountry choropleth globeDescribe your data
onErrorWebGL initialization or context-loss errors
className / styleApplied to the container

Each data entry must have a unique country code. Duplicate alpha2 values throw an error.

Colors

Colors range from the smallest to largest absolute value among supported countries in your data. Values of 10 and −10 get the same color. For a logarithmic ramp with nonnegative values, pass Math.log1p(value) as each entry’s value. Keep the original values for tooltip formatting.

Selection and tooltips

Active entries rotate into view and pause idle rotation. Ref methods: setActiveEntry(id) requests an active entry, clearActiveEntry() requests clearing it, and navigateToEntry(id) only rotates. The first two call onActiveEntryChange; controlled callers apply the requested change. Pointer hover reports a country through onCountryHover without changing the active entry.

Tooltips receive { source, alpha2, entry, entryId, label, formattedValue, x, y }. The x and y coordinates position your tooltip in CSS pixels relative to the globe. Countries outside your data have no entry or formatted value. Provide formatValue to format values for display.

Accessibility

Always include an aria-label with a text summary. Reduced motion stops idle rotation automatically. Interactive globes support keyboard rotation.

For a static globe image, pass interactive={false} and autoRotate={false} and chlobe will set an image role.