Globe

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Usage

Rows need a longitude and a latitude, plus a name for the tooltip. The land is worldCountries, installed in components/charts/data/ with any example that uses it.

import { worldCountries } from "@/components/charts/data/world-countries";
import {
  GlobeChart,
  GlobeLand,
  GlobeMarkers,
  GlobeSphere,
  GlobeTooltip,
} from "@/components/ui/charts";

const offices = [
  { latitude: 51.51, longitude: -0.13, name: "London" },
  { latitude: 52.52, longitude: 13.4, name: "Berlin" },
  { latitude: 40.71, longitude: -74.01, name: "New York" },
  { latitude: 1.35, longitude: 103.82, name: "Singapore" },
];

export const OfficesGlobe = () => (
  <GlobeChart
    ariaLabel="Our offices"
    center={[10, 30]}
    data={offices}
    geography={worldCountries}
  >
    <GlobeSphere />
    <GlobeLand />
    <GlobeMarkers />
    <GlobeTooltip />
  </GlobeChart>
);

Anatomy

The layers stack in a fixed order: the ocean, the graticule, the land, then the markers.

<GlobeChart center={[12, 30]} data={regions} geography={worldCountries}>
  <GlobeSphere />
  <GlobeGraticule />
  <GlobeLand />
  <GlobeMarkers />
  <GlobeTooltip />
</GlobeChart>

• GlobeChart: Holds the places, the countries and the projection, and turns it on drag.
• GlobeSphere: The ocean and the globe's rim.
• GlobeGraticule: Lines of longitude and latitude, every 20° by default.
• GlobeLand: The countries from geography.
• GlobeMarkers: A dot on each place, one size or scaled by dataKey.
• GlobeTooltip: The marker's name and, with dataKey, its value.

Turning the globe

center is the [longitude, latitude] that faces the reader, [10, 20] by default. A drag turns the globe from there, 0.35° per pixel, and the tilt stops at 80° so it never rolls over a pole.

Markers on the far side are hidden and take no hover until they come round. The tooltip is hidden while the globe turns.

Touch screens

On a touch screen, a finger on the globe turns it instead of scrolling the page or opening a tooltip. Where that gets in the way, for example in a narrow column on a phone, set draggable={false}: taps then show the tooltips.

Sized markers

Give <GlobeMarkers> a dataKey and each marker's area follows its value, the largest drawn at radius. Without a dataKey, every marker takes radius, 5 px by default.

The largest markers are drawn first, so small ones stay on top. The tooltip adds the value under the place's name.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

className goes on the chart's container, so size and spacing are utility classes.

Every layer's colors are props: fill and stroke on <GlobeSphere>, fill, stroke and strokeWidth on <GlobeLand>, color on <GlobeMarkers>. content on <GlobeTooltip> gets the hovered row as marker.

<GlobeChart center={[-60, 15]} data={customers} geography={worldCountries}>
  <GlobeSphere fill="var(--muted)" />
  <GlobeLand fill="var(--chart-scale-03)" stroke="var(--muted)" />
  <GlobeMarkers color="var(--chart-2)" dataKey="customers" radius={14} />
  <GlobeTooltip
    content={({ marker }) => (
      <div className="px-3 py-2 text-sm">
        {String(marker.name)}: {Number(marker.customers).toLocaleString()}
      </div>
    )}
  />
</GlobeChart>

Where a part renders content of its own, you pass it in. In React:

• GlobeTooltip: content={({ marker, index }) => …}

Loading state

With status="loading", a skeleton disc and the land's outline breathe in the globe's place under its graticule, with a few skeleton markers. Dragging and hover are off until "ready", when the globe grows in.

loadingLabel puts a short line of text over it.

Animation

The globe grows in over 700 ms, the land fades in from 150 ms, and the markers pop in from 450 ms, largest first, spread over animationDuration (900 ms).

Dragging never replays it. animate={false} and reduced motion both draw the globe at rest.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

The ocean is --chart-scale-01 and the land --chart-scale-02, both mixed from --chart-1 into --muted, so the globe follows your theme's first chart color. Country borders take the ocean's color and the rim is --border.

:root {
  --chart-background: var(--background);
  --chart-tooltip-background: var(--card);
}

Accessibility

The globe is announced as an image named by ariaLabel ("Globe" by default). Arrow keys move through the markers on the side facing the reader, left to right.

The keyboard can't turn the globe, and markers on the far side can't be focused. If those places matter, name them in ariaDescription or list them next to the chart.

API reference

GlobeChart

GlobeSphere

GlobeLand

GlobeGraticule

GlobeMarkers

GlobeTooltip