globe-kit

Drop any dataset onto a 3D globe with grid snapping, entrance animations, themes, and full React customization.

Built on r3f-globe and Three.js.

Install

npm install globe-kit

Peer dependencies (you likely already have these):

npm install react react-dom three @react-three/fiber @react-three/drei

Quick Start

import { Globe } from "globe-kit"

const cities = [
  { name: "Tokyo", lat: 35.68, lng: 139.69 },
  { name: "Paris", lat: 48.86, lng: 2.35 },
  { name: "NYC",   lat: 40.71, lng: -74.01 },
]

export default function App() {
  return <Globe data={cities} lat="lat" lng="lng" />
}

Full Example

import { Globe } from "globe-kit"

const restaurants = [
  { id: "1", name: "Sukiyabashi Jiro", lat: 35.67, lng: 139.76, emoji: "\ud83c\udf63" },
  { id: "2", name: "Noma",             lat: 55.68, lng: 12.61, emoji: "\ud83c\udf3f" },
  { id: "3", name: "El Celler",        lat: 41.98, lng: 2.82, emoji: "\ud83c\udf77" },
]

export default function App() {
  return (
    <Globe
      data={restaurants}
      lat="lat"
      lng="lng"
      icon="emoji"
      id="id"
      theme="ocean"
      entrance="sprout"
      entranceDuration={2.5}
      gridSize={5}
      autoRotate
      autoRotateSpeed={0.3}
      labels={{ continents: true, oceans: true }}
      starfield
      onClick={(item, e) => console.log("Clicked:", item.name)}
      onHover={(item) => console.log("Hovered:", item?.name)}
      tooltip={(item) => <div>{item.name}</div>}
      detailPanel={(item, onClose) => (
        <div>
          <h2>{item.name}</h2>
          <button onClick={onClose}>Close</button>
        </div>
      )}
    />
  )
}

API Reference

<Globe> Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | D[] | required | Array of items to place on the globe | | lat | Accessor<D, number> | required | Latitude accessor (function, key string, or static value) | | lng | Accessor<D, number> | required | Longitude accessor | | icon | Accessor<D, string \| Object3D> | undefined | Icon accessor (emoji, image URL, or Three.js Object3D) | | id | Accessor<D, string> | undefined | Unique ID accessor for selection tracking |

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | gridSize | number | 5 | Grid cell size in degrees. 0 = exact coordinates | | gridElevation | number | 0.06 | How high grid lines float above the surface | | iconElevation | number | 0.005 | How high icons sit above the surface | | iconSize | number | 7 | Icon size in world units |

Camera

| Prop | Type | Default | Description | |------|------|---------|-------------| | minDistance | number | 200 | Min camera distance (max zoom in) | | maxDistance | number | 500 | Max camera distance (max zoom out) | | initialDistance | number | 350 | Starting camera distance | | autoRotate | boolean | true | Enable auto-rotation | | autoRotateSpeed | number | 0.3 | Rotation speed | | rotateSpeed | number | 0.25 | Manual rotate sensitivity |

Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | string \| GlobeTheme | "catppuccin-mocha" | Built-in theme name or custom theme object | | starfield | boolean | true | Show background stars | | starfieldCount | number | 2000 | Number of stars | | globeImage | string | "blue-marble" | Globe texture (built-in name or URL) | | bumpMap | boolean | true | Enable surface bump mapping | | atmosphereAltitude | number | 0.18 | Atmosphere glow height |

Labels

| Prop | Type | Default | Description | |------|------|---------|-------------| | labels | LabelConfig \| boolean | undefined | Built-in label layers ({ continents, countries, oceans, coordinates }) | | customLabels | CustomLabel[] | undefined | Additional custom labels ({ text, lat, lng, size? }) |

Animation

| Prop | Type | Default | Description | |------|------|---------|-------------| | entrance | EntranceType | "sprout" | Entrance animation type | | entranceDuration | number | 2.5 | Total entrance duration (seconds) | | entranceStagger | number | 2.0 | Max stagger delay (seconds) |

Interaction

| Prop | Type | Default | Description | |------|------|---------|-------------| | onClick | (item: D, event: MouseEvent) => void | undefined | Item click handler | | onHover | (item: D \| null) => void | undefined | Hover handler | | selectedId | string \| null | undefined | Controlled selected item ID (triggers fly-to) |

UI Slots (Render Props)

| Prop | Type | Description | |------|------|-------------| | tooltip | (item: D) => ReactNode | Hover tooltip renderer | | detailPanel | (item: D, onClose: () => void) => ReactNode | Detail panel renderer | | filterBar | () => ReactNode | Filter bar renderer | | header | () => ReactNode | Header renderer |

Built-in Themes

| Name | Description | |------|-------------| | catppuccin-mocha | Warm purple/peach tones (default) | | sepia | Vintage parchment feel | | ocean | Deep blue with cyan accents | | midnight | Monochrome black and white | | aurora | Northern lights green palette |

Pass a theme name as a string, or provide a custom GlobeTheme object.

Entrance Animations

| Name | Effect | |------|--------| | sprout | Icons spring up with elastic easing (default) | | fade | Icons fade in with staggered timing | | scatter | Icons scatter in from random positions | | none | No animation, items appear immediately |

Exports

import { Globe, themes } from "globe-kit"
import type { GlobeProps, GlobeTheme, LabelConfig, CustomLabel, EntranceType, Accessor } from "globe-kit"

Credits

• r3f-globe / three-globe by Vasco Asturiano
• Three.js and React Three Fiber

License

MIT -- Andy8647