chlobe: a 15kb React choropleth globe, inspired by the brilliant cobe.
pnpm add @lachlanjc/chlobeDarker dots, more forest per person · logarithmic scale
Globe: logarithmic color scale · bars: annual production
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.
Install cobe to visualize country data per https://raw.githubusercontent.com/lachlanjc/chlobe/refs/heads/main/README.mdRequires React 18+ and WebGL:
pnpm add @lachlanjc/chlobeRender a globe with an RGB color ramp (it’s more efficient for shaders):
'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}/>Hover or focus a legend button to highlight its country. Click it to rotate the globe there.
'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> ))} </> );};Hover a country to see its name and renewable electricity share. Countries outside the dataset show “No data”.
'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> )}/>| Property | Default | Description |
|---|---|---|
| data | Required | Country entries: unique alpha2, value, optional id and label · IDs default to alpha2 |
| colors | Required | Two filled RGB tuples and one missing tuple; channels 0–255 |
| colors.missingAlpha | 0.25 | Missing-country opacity |
| colors.base / colors.glow | Color scheme | Surface and glow RGB tuples |
| colorScheme | light | Light or dark shading and default surface and glow colors; custom colors override the defaults |
| size | Container width | Square size in CSS pixels |
| autoRotate | true | Idle rotation |
| interactive | true | Dragging, hover, and left/right arrows |
| initialPhi | 0 | Starting rotation in radians |
| activeEntryId | Uncontrolled | Selected ID; null clears · Pair with onActiveEntryChange |
| defaultActiveEntryId | null | Initial uncontrolled selection |
| onActiveEntryChange | Requested active ID or null from ref methods | |
| onCountryHover | Pointer country code or null; independent of selection | |
| formatValue | Formats (value, entry) | |
| renderTooltip | Custom tooltip UI; absent by default | |
| aria-label | Country choropleth globe | Describe your data |
| onError | WebGL initialization or context-loss errors | |
| className / style | Applied to the container |
Each data entry must have a unique country code. Duplicate alpha2 values throw an error.
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.
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.
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.