Globe

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add globe

Usage#

The Globe is square and fills its width, so cap it with a max-w-*. It shares the Map's coordinates, [longitude, latitude], and its markers: anything that works inside MapMarker, MapPin in every shape included, works inside GlobeMarker. Use the Map to find a street; use the Globe to show where in the world things are.

Anatomy#

import { Globe, GlobeMarker, GlobeArc } from "@/components/ui/globe"

<Globe>
  <GlobeArc from={…} to={…} />
  <GlobeMarker lngLat={…}>…</GlobeMarker>
</Globe>

Markers#

Markers stay in your tree, so Context, state and events work as usual. They fade out at the edge of the sphere rather than popping, and a marker behind the globe stops taking the pointer. Every marker stays in the accessibility tree as an item of the marker list, and tabbing to an interactive one turns the globe to face it. A dot with a captionkeeps the map readable; a labelled chip suits one or two places.

Routes#

GlobeArc draws the shortest path between two points, lifted more the further it travels. Routes draw in one after another by order, land with a ring, then send a short pulse along themselves now and then. Many to many reads as a network; keep the markers small, such as MapPin shape="dot" with a caption, so the routes lead.

Day and night#

daylight veils the half of the world in darkness, from the sun's real position, and follows the clock as it turns. Pass a Date to show another moment. Pair it with local times in the markers for a distributed team or the status of regions.

Select countries#

selectionMode turns the globe into a picker. Hovering a country tints it, traces its outline and names it with its flag beside the pointer, with a check once it is picked. The label holds for a beat across a border or a strait, so it glides from one country to the next instead of blinking, and turns below the pointer near the top edge. A click fills the country in ink, and the hairline borders keep neighbours apart. countries limits the choice, here to Europe, and rests everything else lighter; zoom frames the region. Selection is ISO codes, the same as Flag, so the list beside the globe is yours to compose. Behind the canvas sits a real checkbox per country (radios in "single" mode): tabbing through them turns the globe to each one, and Space picks it.

"single" keeps one country, for a shipping or billing country picked on the map. A second click on it clears the choice.

Surface#

Every colour is a mix of the theme's ink and background, with no accent, read from the --globe-* variables, so the globe re-paints in place when the theme changes and any one of them can be re-tinted with a utility. graticule adds hairline meridians and parallels; sphere={false} leaves the land on the page inside a hairline outline.

Still#

autoRotate={false} and draggable={false} make a still globe framed on center, for a contact page or a card. It draws once and then only when the theme or its size changes.

API reference#

FAQ#