# ASCII globe

A lit, rotating planet in glyphs with a day and night terminator, ocean glints, an atmosphere, markers and arcs.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. The asciicn agent skill, for building any ASCII effect on the engine, is at [/.well-known/agent-skills/asciicn/SKILL.md](/.well-known/agent-skills/asciicn/SKILL.md).

> **This is an example, not the only option.** It is one component built on the asciicn engine. Install it when it is what you were asked for. For any other look, don't stretch its props to fit: write your own field on `AsciiShader` ([Write your own](/docs/engine/write-your-own.md)), or draw a CPU grid with `AsciiGrid`, and read this example's source for technique. Its full source is in [https://asciicn.dev/r/ascii-globe.json](https://asciicn.dev/r/ascii-globe.json), under `files[].content`.

## Installation [#installation]

```bash
npx shadcn@latest add https://asciicn.dev/r/ascii-globe.json
```

## Usage [#usage]

```tsx
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 [#examples]

### Horizon behind a headline [#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 [#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 [#props]

Every [ASCII image](/docs/images/ascii-image#props) look prop also applies, with `charset` defaulting to `"braille"`, plus `fx` for a CRT finish.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `markers` | `{ at: [lat, lon]; color?: AsciiColor }[]` | `[]` | Pulsing locations. Markers on the far side are hidden. |
| `arcs` | `{ from: [lat, lon]; to: [lat, lon]; color?: AsciiColor }[]` | `[]` | Great-circle arcs lifted off the surface, with a light running along them. |
| `color` | `AsciiColor` | `"green"` | Land colour in truecolor. |
| `oceanColor` | `AsciiColor` | `"blue"` | Sea and atmosphere colour in truecolor. |
| `accent` | `AsciiColor` | `"orange"` | Colour of markers and arcs that don't set their own. |
| `speed` | `number` | `6` | Degrees of rotation per second. Negative spins the other way. |
| `start` | `number` | `10` | Longitude facing the viewer at the start, in degrees. |
| `tilt` | `number` | `18` | How far the north pole leans towards the viewer, in degrees. |
| `light` | `number` | `300` | Where the sun is, in degrees clockwise from the top. |
| `ocean` | `number` | `0.3` | Brightness of the sea on the day side, 0 to 1. |
| `atmosphere` | `boolean` | `true` | Limb light and a halo on the lit side. |
| `graticule` | `boolean` | `false` | Faint latitude and longitude lines every 30° over the sea. |
| `colorMode` | `"mono" \| "truecolor" \| "ansi16" \| "duotone" \| "palette"` | `"truecolor"` | How glyphs are coloured. |
| `draggable` | `boolean` | `true` | Drag or use the arrow keys to turn and tilt it. It coasts after a drag. |
| `cell` | `number` | `10` | Glyph cell height in CSS pixels. |
| `animate` | `boolean` | `true` | Spin and pulse. false draws one still frame. |
| `handle` | `RefObject<AsciiHandle \| null>` |  | Filled with a handle for export. |

## Notes [#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-label` to 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-land` mask (Natural Earth, public domain), installed with the component. Nothing is fetched at runtime.