@aeryflux/globe

Portable 3D globe component for React and React Native (Expo). Built on Three.js with music-reactive visuals, data visualization, and ambient wave animations.

Live Demo | npm | AeryFlux

Features

• Cross-platform — React (web) and React Native (Expo)
• Three.js powered — WebGL rendering with post-processing bloom
• Data visualization — highlight countries and cities with custom colors and extrusion
• Music reactivity — bass, energy, and BPM-driven rotation and wave intensity
• Ambient wave — dual gaussian sweep with optional radial extrusion (hola effect)
• Intro animation — slide-in from left with spin
• Dynamic gradients — real-time background and globe fill tint updates
• 3 surface themes — dark, green, white
• City markers — 185 major cities with hexagonal borders
• CDN-served models — pre-generated GLB files (212KB to 20MB)
• SVG fallback — graceful degradation when WebGL is unavailable

Installation

npm install @aeryflux/globe three

Quick Start

React (Web)

import { Globe } from '@aeryflux/globe/react';

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <Globe
        surface="green"
        showCountries
        rotationSpeed={0.0005}
      />
    </div>
  );
}

React Native (Expo)

import {
  buildGlobeIndex,
  applyGlobeMaterials,
  getSurfaceColors,
  createGlobeScene,
  createGlobeCamera,
  animateGlobeRotation,
  animateBorderPulse,
} from '@aeryflux/globe/react-native';

The React Native export provides core animation functions for manual Three.js setup with expo-gl and expo-three.

Props

Appearance

Prop	Type	Default	Description
surface	'dark' | 'green' | 'white'	'green'	Color theme
borderColor	string	-	Override border/accent color
countryColor	string	-	Override country fill color
globeFillColor	string	-	Override ocean fill color
glowIntensity	number	1.2	Border glow intensity
bloomStrength	number	1.0	Post-processing bloom
isLightTheme	boolean	false	Reduce bloom for light backgrounds
forceTransparent	boolean	false	Force transparent background

Display

Prop	Type	Default	Description
showCountries	boolean	true	Show country fills
showBorders	boolean	true	Show border lines
showGlobeFill	boolean	true	Show ocean/globe
showCities	boolean	false	Show city markers

Interaction

Prop	Type	Default	Description
enableControls	boolean	false	Enable orbit controls (drag, zoom)
rotationSpeed	number	0.0003	Auto-rotation speed
onCountryClick	(name: string) => void	-	Country click handler (requires enableControls)

Data Visualization

Prop	Type	Default	Description
countryData	Record<string, DataPoint>	-	Country highlights
cityData	Record<string, DataPoint>	-	City highlights
dataHighlightColor	string	accent	Default highlight color

DataPoint: { scale: number; color?: string; extrusion?: number }

Ambient Wave

Prop	Type	Default	Description
ambientColor	string	accent	Wave accent color
ambientIntensity	number	0.4	Wave intensity (0-1)
ambientExtrusion	number	0	Radial displacement on wave peaks (0 = off, 1 = full)

Music Reactivity

Prop	Type	Default	Description
bass	number	0	Bass level (0-1.5) — boosts rotation and wave
mid	number	0	Mid frequency level (0-1)
treble	number	0	Treble level (0-1)
energy	number	0	Overall energy (0-1) — boosts rotation and wave

Dynamic Background

Prop	Type	Default	Description
gradientTop	string	'#06060e'	Background gradient top color
gradientBottom	string	'#0e1430'	Background gradient bottom color
globeFillTint	string	-	Real-time globe fill tint override

Intro Animation

Prop	Type	Default	Description
introAnimation	boolean	false	Enable slide-in + spin entry
introDuration	number	2.5	Animation duration in seconds

Other

Prop	Type	Default	Description
modelUrl	string	CDN	Custom GLB model URL
className	string	-	CSS class
style	CSSProperties	-	Inline styles
debug	boolean	false	Debug mode

Data Visualization

import { Globe } from '@aeryflux/globe/react';

const countryData = {
  France: { scale: 0.8, color: '#ef4444' },
  Japan: { scale: 0.6, color: '#3b82f6', extrusion: 0.5 },
  Brazil: { scale: 1.0, color: '#22c55e' },
};

<Globe
  surface="dark"
  showCountries
  countryData={countryData}
  dataHighlightColor="#00ff88"
/>

Music-Reactive Globe

<Globe
  surface="dark"
  showCountries
  ambientIntensity={0.6}
  ambientExtrusion={0.3}
  bass={bassLevel}
  energy={energyLevel}
  rotationSpeed={0.0005}
  gradientBottom="#1a0a00"
/>

Bass and energy values drive rotation speed, wave sweep velocity, and extrusion displacement in real-time.

Dev Tools

import { Globe, GlobeDevTools } from '@aeryflux/globe/react';

const [config, setConfig] = useState<GlobeConfig>({ surface: 'green' });

<Globe {...config} />
<GlobeDevTools
  config={config}
  onChange={(partial) => setConfig(prev => ({ ...prev, ...partial }))}
  side="right"
/>

Interactive panel with toggles for all visual options: ocean, countries, borders, cities, controls, glow, speed, bloom, bass, energy, and ambient settings.

Models

Models are served from jsDelivr CDN by default.

Model	Size	Use Case
atlas_hex_subdiv_5.glb	2MB	Mobile
atlas_hex_subdiv_6.glb	7MB	Desktop
atlas_hex_subdiv_7.glb	20MB	High quality (default)
weather_hex_globe_subdiv_3.glb	212KB	Weather overlay

// Use a smaller model for mobile
<Globe modelUrl="https://cdn.jsdelivr.net/npm/@aeryflux/globe@0.7.3/models/atlas_hex_subdiv_5.glb" />

// Self-host models
<Globe modelUrl="/models/atlas_hex_subdiv_7.glb" />

Surfaces

Surface	Accent	Background	Countries
dark	#00ff88	#050508	Light gray
green	#00ff88	#050508	Light gray
white	#1a1a1a	#ffffff	Light gray

Exports

@aeryflux/globe/react

Globe, GlobeFallback, GlobeDevTools, useWebGLSupport
SURFACES, GLOBE_MODELS
animateDataHighlights, animateCityHighlights
// + all types

@aeryflux/globe/react-native

buildGlobeIndex, getSurfaceColors, applyGlobeMaterials
createGlobeScene, createGlobeCamera
animateGlobeRotation, animateBorderPulse, animateAmbientWave
animateDataHighlights, animateCityHighlights
resetAllCountries, resetAllCities
updateGradient, updateGlobeFillTint, updateAccentLight
createIntroState, applyIntroAnimation
// + all types

License

MIT - AeryFlux

Credits

• Three.js - 3D rendering
• geojsonto3D - Globe model generation
• Natural Earth - Geographic data