3D Globe Chart

Quick Start

import { Globe3D } from "@chartts/gl"
 
const chart = Globe3D("#chart", {
  data: {
    series: [
      {
        name: "Revenue",
        values: [850, 620, 430, 380, 290, 210],
        x: [-73.9, -0.1, 139.7, 77.2, -43.2, 103.8],
        y: [40.7, 51.5, 35.7, 28.6, -22.9, 1.3],
      },
    ],
    categories: [
      "New York", "London", "Tokyo",
      "Mumbai", "Sao Paulo", "Singapore",
    ],
  },
})

That renders a high-resolution 3D globe with data points projected onto the sphere surface as glowing patches. The globe auto-rotates by default, shows subtle graticule lines at 30-degree intervals, and labels each data location. Larger values produce brighter, wider glowing regions on the surface.

When to Use Globe Charts

Globe charts place geographic data on a 3D sphere, making them ideal for showing worldwide distribution patterns where spatial relationships across hemispheres matter.

Use a globe chart when:

• Showing the global distribution of data (offices, users, events)
• The spatial relationship between hemispheres is important
• You want a visually striking hero visualization for dashboards
• Data points are distributed across multiple continents

Don't use a globe chart when:

• Data is concentrated in a single region (use a flat map)
• You need precise geographic boundaries (use a GeoJSON-based map)
• The back of the globe hides important data points
• The visualization will not be interactive (half the data is always hidden)

Props Reference

Auto-Rotation

The globe auto-rotates by default, slowly spinning to reveal all data points. Auto-rotation pauses when the user interacts (drag, zoom) and resumes after they stop.

Globe3D("#chart", {
  data: globeData,
  orbit: {
    autoRotate: true,
    autoRotateSpeed: 0.8,
  },
})

To start the globe stationary:

Globe3D("#chart", {
  data: globeData,
  orbit: { autoRotate: false },
})

Latitude and Longitude Projection

Data points use y for latitude and x for longitude, matching standard geographic conventions. Values are projected onto a sphere using spherical coordinate conversion.

Globe3D("#chart", {
  data: {
    series: [
      {
        name: "Offices",
        values: [100, 80, 60, 40],
        x: [-122.4, 2.3, 121.5, 55.3],
        y: [37.8, 48.9, 31.2, 25.3],
      },
    ],
    categories: [
      "San Francisco", "Paris", "Shanghai", "Dubai",
    ],
  },
})

Each location appears as a glowing colored patch on the globe surface. The glow intensity and radius scale with the normalized value, so larger values create more prominent visual markers.

Graticule Lines

The globe displays subtle latitude and longitude grid lines at 30-degree intervals. These graticule lines are baked directly into the globe mesh vertex colors, so they render with zero overhead and blend smoothly into the dark ocean surface.

The graticule helps users orient themselves and estimate the geographic location of data points. The lines use a subtle dark blue color that does not compete with data patches.

Data Labels

Location labels are drawn as a 2D overlay on top of the 3D scene. Each label appears next to its corresponding data point with a small colored dot matching the location color from the theme palette.

Labels only display when the data point is on the visible side of the globe (not occluded by the sphere). As the globe rotates, labels smoothly appear and disappear as their locations come into and out of view.

Globe3D("#chart", {
  data: {
    series: [
      {
        name: "Users",
        values: [50000, 35000, 28000],
        x: [-74, 13.4, 103.8],
        y: [40.7, 52.5, 1.3],
      },
    ],
    categories: ["New York", "Berlin", "Singapore"],
  },
})

Accessibility

• Tooltip displays location name and exact value on hover
• Each data location is assigned a distinct color from the palette for visual separation
• Labels provide text identification alongside color-coded dots
• Auto-rotation pauses during interaction so users can carefully inspect individual locations

Real-World Examples

Global office locations

Globe3D("#offices", {
  data: {
    series: [
      {
        name: "Employees",
        values: [2500, 1800, 1200, 800, 600, 400],
        x: [-122.4, -0.1, 139.7, 77.2, -46.6, 151.2],
        y: [37.8, 51.5, 35.7, 12.9, -23.5, -33.9],
      },
    ],
    categories: [
      "San Francisco", "London", "Tokyo",
      "Bangalore", "Sao Paulo", "Sydney",
    ],
  },
  orbit: { autoRotate: true, autoRotateSpeed: 0.4 },
  theme: "dark",
})

CDN traffic distribution

Globe3D("#cdn", {
  data: {
    series: [
      {
        name: "Requests/sec",
        values: [45000, 38000, 32000, 28000, 22000, 18000, 12000, 8000],
        x: [-77.0, -0.1, 139.7, 103.8, -43.2, 37.6, 28.9, 121.5],
        y: [38.9, 51.5, 35.7, 1.3, -22.9, 55.8, 41.0, 31.2],
      },
    ],
    categories: [
      "Virginia", "London", "Tokyo", "Singapore",
      "Sao Paulo", "Moscow", "Istanbul", "Shanghai",
    ],
  },
  camera: {
    position: [0, 3, 10],
    target: [0, 0, 0],
  },
})

Earthquake monitoring

Globe3D("#quakes", {
  data: {
    series: [
      {
        name: "Magnitude",
        values: [7.1, 6.4, 5.8, 6.9, 5.5, 7.8, 6.2],
        x: [142.4, -70.8, 26.7, 121.2, 139.1, 88.1, -155.5],
        y: [38.3, -33.4, 38.9, 23.8, 35.4, 28.2, 19.5],
      },
    ],
    categories: [
      "Japan", "Chile", "Turkey", "Taiwan",
      "Tokyo", "Nepal", "Hawaii",
    ],
  },
  orbit: { autoRotate: true, autoRotateSpeed: 0.2 },
})