Realtime Globe 🌍

A high-performance, interactive 3D globe component for React, built with Three.js and Globe.gl. Perfect for visualizing real-time data, visitor tracking, or global networks.

✨ Features

• High-Performance Rendering: Built on Three.js and Globe.gl for smooth 60fps animations.
• Dynamic Themes: Switch between Minimal, Earth Night, and Earth Day modes.
• Interactive Data: Support for Points, Arcs, Rings, and HTML markers.
• Smart Zooming: Automatic level-of-detail adjustments and label visibility.
• Atmospheric Effects: Realistic atmosphere glow and custom backgrounds.
• Fully Typed: Comprehensive TypeScript definitions included.

📦 Installation

This package requires react, react-dom, and three as peer dependencies.

npm install realtime-globe three
# or
yarn add realtime-globe three
# or
pnpm add realtime-globe three

🚀 Basic Usage

import React from 'react';
import { Globe } from 'realtime-globe';

function App() {
  const points = [
    { 
      lat: 40.7128, 
      lng: -74.0060, 
      size: 0.5, 
      color: '#ff0000', 
      label: 'New York' 
    },
    { 
      lat: 51.5074, 
      lng: -0.1278, 
      size: 0.5, 
      color: '#00ff00', 
      label: 'London' 
    }
  ];

  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <Globe 
        points={points}
        config={{
          theme: 'earth-night',
          enableAtmosphere: true
        }}
        onPointClick={(point) => console.log('Clicked:', point)}
      />
    </div>
  );
}

📖 API Reference

<Globe /> Component

The main component for rendering the 3D globe.

Prop	Type	Description
config	GlobeConfig	Configuration object for visual appearance.
points	DataPoint[]	Array of points to render on the globe surface.
arcs	ArcData[]	Array of arcs (lines) connecting points.
rings	RingData[]	Array of animated rings (ripples) at specific coordinates.
labels	LabelData[]	Text labels to display at coordinates.
htmlElements	VisitorData[]	Custom HTML markers (useful for avatars/tooltips).
width	number	Width of the globe container (defaults to 100%).
height	number	Height of the globe container (defaults to 100%).
onPointClick	(point, event, coords) => void	Callback when a point is clicked.
onGlobeReady	() => void	Callback when the globe is fully initialized.

Configuration (GlobeConfig)

Pass this object to the config prop to customize the globe's appearance.

Property	Type	Default	Description
theme	'minimal' | 'earth-night' | 'earth-day' | 'earth-blue'	'minimal'	Preset visual themes.
enableAutoRotate	boolean	false	Whether the globe should rotate automatically.
autoRotateSpeed	number	0.5	Speed of auto-rotation.
enableAtmosphere	boolean	true	Show atmospheric glow.
atmosphereColor	string	'#3a228a'	Color of the atmosphere.
backgroundColor	string	'#000011'	Background color of the scene.
globeImageUrl	string	null	Custom texture URL for the globe surface.
bumpImageUrl	string	null	Custom bump map URL for topography.

Data Types

DataPoint

interface DataPoint {
  lat: number;
  lng: number;
  color?: string;
  size?: number;
  altitude?: number;
  label?: string;
  customData?: any;
}

ArcData

interface ArcData {
  startLat: number;
  startLng: number;
  endLat: number;
  endLng: number;
  color?: string | string[];
  altitude?: number;
  strokeWidth?: number;
  dashLength?: number;
  animationTime?: number;
}

🛠️ Local Development

To run the example dashboard included in this repository:

1. Clone the repository

   git clone https://github.com/yourusername/realtimeglobe.git
   cd realtimeglobe

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

📄 License

MIT