Installation
pnpm dlx shadcn@latest add https://asciicn.dev/r/ascii-globe.jsonUsage
import { AsciiGlobe } from "@/components/asciicn/ascii-globe";
const LONDON = [51.51, -0.13] as const;
const TOKYO = [35.68, 139.69] as const;
export function Global() {
return (
<AsciiGlobe
markers={[{ at: LONDON }, { at: TOKYO }]}
arcs={[{ from: LONDON, to: TOKYO }]}
className="aspect-square w-full max-w-md"
/>
);
}Each sample casts a ray at the sphere and reads land from the shared world-land mask. The sun, set by light, draws a soft terminator. Past it, the land keeps a faint outline so the night side never goes blank. The sea catches a specular glint near the sun, the air thickens at the lit limb, and a thin halo glows outside it. Land above 70° fades to ice.
In truecolor, land takes color and sea and air take oceanColor. Markers and arcs keep their accent in every colour mode, mono included.
The globe stays round and centred and takes 86% of the box's shorter side. Make the box larger than its section and offset it to show only the top, as in the first example.
It does not react to hover. Press and drag sideways to spin it and up or down to tilt it. Let go mid-drag and it coasts, then picks its spin back up. On phones a horizontal swipe turns it and a vertical swipe still scrolls the page. With keyboard focus, the arrow keys turn it. Set draggable={false} for a globe that only spins on its own.
Examples
Horizon behind a headline
A globe 150% of the section's width, pushed below the bottom edge so only its lit top shows, on a transparent background.
Amber phosphor with a graticule
speed={0} and start at the marker's longitude hold one region in view, while the graticule draws a line every 30°.
Props
Every ASCII image look prop also applies, with charset defaulting to "braille", plus fx for a CRT finish.
| Prop | Type | Default |
|---|---|---|
| markers Pulsing locations. Markers on the far side are hidden. | Type: { at: [lat, lon]; color?: AsciiColor }[] | Default [] |
| arcs Great-circle arcs lifted off the surface, with a light running along them. | Type: { from: [lat, lon]; to: [lat, lon]; color?: AsciiColor }[] | Default [] |
| color Land colour in truecolor. | Type: AsciiColor | Default "green" |
| oceanColor Sea and atmosphere colour in truecolor. | Type: AsciiColor | Default "blue" |
| accent Colour of markers and arcs that don't set their own. | Type: AsciiColor | Default "orange" |
| speed Degrees of rotation per second. Negative spins the other way. | Type: number | Default 6 |
| start Longitude facing the viewer at the start, in degrees. | Type: number | Default 10 |
| tilt How far the north pole leans towards the viewer, in degrees. | Type: number | Default 18 |
| light Where the sun is, in degrees clockwise from the top. | Type: number | Default 300 |
| ocean Brightness of the sea on the day side, 0 to 1. | Type: number | Default 0.3 |
| atmosphere Limb light and a halo on the lit side. | Type: boolean | Default true |
| graticule Faint latitude and longitude lines every 30° over the sea. | Type: boolean | Default false |
| colorMode How glyphs are coloured. | Type: "mono" | "truecolor" | "ansi16" | "duotone" | "palette" | Default "truecolor" |
| draggable Drag or use the arrow keys to turn and tilt it. It coasts after a drag. | Type: boolean | Default true |
| cell Glyph cell height in CSS pixels. | Type: number | Default 10 |
| animate Spin and pulse. false draws one still frame. | Type: boolean | Default true |
| handle Filled with a handle for export. | Type: RefObject<AsciiHandle | null> | Default – |
Notes
- A draggable globe is focusable and announced as an image labelled "Globe. Drag it or use the arrow keys to turn it." Pass your own
aria-labelto say what it shows. - Under reduced motion it draws one still frame, markers included.
- It draws at up to 60 fps and pauses offscreen and in hidden tabs. A 600px globe in Braille at 10px cells shades about 58,000 samples per frame.
- Land comes from the
world-landmask (Natural Earth, public domain), installed with the component. Nothing is fetched at runtime.