# Tokyo

Tokyo at night in coloured dots, built in 3D: the Tokyo Skytree in pale blue light over a dense city that runs to the horizon, with neon on the near streets, Tokyo Tower small in the distance and a moonlit Mount Fuji under a teal sky.

> 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/tokyo.json](https://asciicn.dev/r/tokyo.json), under `files[].content`.

## Installation [#installation]

```bash
npx shadcn@latest add https://asciicn.dev/r/tokyo.json
```

## Usage [#usage]

```tsx
import { Tokyo } from "@/components/asciicn/tokyo";

export function Hero() {
  return (
    <section className="relative isolate min-h-[480px]">
      <Tokyo intensity={0.6} className="absolute inset-0 -z-10" />
      <h1>Your headline</h1>
    </section>
  );
}
```

The view looks west from a rooftop in the east of the city, 64 m up. The scene is built in 3D and raymarched from that camera: the city is a grid of lots, each with its own block, walked front to back so every wall, roof and street is a real surface at a real distance. The grid runs at an angle to the view, so blocks show two faces and the avenues run off toward the horizon as lines of light. Past a few kilometres the city carries on in long steps until it melts into the haze.

The Tokyo Skytree stands at the right, about 1.7 km away, drawn to its real proportions: a tripod base that narrows into a round lattice shaft, the three-tier Tembo Deck at 350 m, the Tembo Galleria ring at 450 m and the antenna mast to 634 m. It is lit in pale blue round a white core, its decks bright and rimmed in violet, with red lights on the mast. Tokyo Tower stands far off at the left, small and orange. Mount Fuji rises a few degrees above the horizon, 90 km away, its snow cap bright on the side facing the low moon.

Light comes from the moon in the west, the glow of the sky, warm street light caught in the low haze, and the city's own lights: office floors in white and cyan, homes in warm light, vertical neon signs on the near streets and red aircraft lights on the tall roofs. Haze thickens with distance, so each layer of blocks is a little lighter than the one in front of it.

Motion is slow and sparse: a few windows switch on or off over tens of seconds, aircraft lights pulse out of step, traffic creeps along the avenues, the neon breathes, haze drifts and stars twinkle. Nothing responds to the pointer.

It draws in `dots` by default on square 7px cells, about 200 columns across a 1440px screen. Every colour is snapped to a palette of 46 chosen for the scene, and dot size follows brightness through `bayer4` ordered dithering, so it reads like a print. In `truecolor`, the default, it paints its own night on a night paper, so it looks the same on light and dark pages. The Skytree stays right of centre on a wide screen; in a tall box the view narrows and gains height, so the tower fills a phone.

The central band, the middle half of the width from 30% to 65% of the height, holds sky and the far horizon. `intensity` dims the colours and shrinks the dots, most of all in that band. Lower it to keep text on top easy to read.

## Examples [#examples]

### Behind a headline [#behind-a-headline]

Full-bleed behind a centred headline and two buttons. `intensity={0.6}` quiets the middle band so the text reads first, while the Skytree and the city still frame it.

```tsx title="examples/tokyo-hero.tsx"
import { Tokyo } from "@/components/asciicn/tokyo";

// Full-bleed behind a centred headline. At 0.6 intensity the middle band,
// where the text sits, drops back most, and the Skytree and the city still
// read.
export default function TokyoHero() {
  return (
    <section className="relative isolate flex size-full min-h-[480px] flex-col items-center justify-center gap-5 overflow-hidden bg-[#050b0e] px-6 py-16 text-center text-white">
      <Tokyo intensity={0.6} className="absolute inset-0 -z-10" />
      <h3 className="[text-shadow:0_1px_12px_rgb(7_8_24)] max-w-xl text-4xl font-medium tracking-[-0.03em] text-balance sm:text-5xl">
        Ship before the last train
      </h3>
      <p className="[text-shadow:0_1px_12px_rgb(7_8_24)] max-w-md text-sm text-pretty text-white/90 sm:text-base">
        Tokyo at night in coloured dots, calm enough to sit behind your
        headline.
      </p>
      <div className="flex flex-wrap items-center justify-center gap-3">
        <a
          href="#get-started"
          className="rounded-full bg-[#fcb442] px-5 py-2.5 text-sm font-medium text-[#1a1203] transition-colors hover:bg-[#ffc560]"
        >
          Get started
        </a>
        <a
          href="#docs"
          className="rounded-full border border-white/25 bg-black/30 px-5 py-2.5 text-sm font-medium text-white backdrop-blur-sm transition-colors hover:bg-black/45"
        >
          Read the docs
        </a>
      </div>
    </section>
  );
}
```

### In a tall card [#in-a-tall-card]

In a 9:19 box the view narrows and gains height, so the Skytree fills the frame above the city.

```tsx title="examples/tokyo-tall.tsx"
import { Tokyo } from "@/components/asciicn/tokyo";

// A phone-shaped card: the view narrows and gains height, so the Skytree
// fills the frame above the city.
export default function TokyoTall() {
  return (
    <div className="relative isolate aspect-[9/19] w-56 overflow-hidden rounded-[2rem] border border-white/10 bg-[#050b0e]">
      <Tokyo className="absolute inset-0" />
    </div>
  );
}
```

### In sodium duotone [#in-sodium-duotone]

`colorMode="duotone"` with `ramp="sodium"` runs every dot's tone through one amber ramp, so dot size alone draws the Skytree, the city and Fuji.

```tsx title="examples/tokyo-duotone.tsx"
import { Tokyo } from "@/components/asciicn/tokyo";

// Duotone runs each dot's tone through one ramp: the city in sodium amber,
// drawn by dot size alone.
export default function TokyoDuotone() {
  return (
    <div className="relative isolate h-80 w-full max-w-2xl overflow-hidden rounded-xl bg-[#0d0600]">
      <Tokyo colorMode="duotone" ramp="sodium" className="absolute inset-0" />
    </div>
  );
}
```

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intensity` | `number` | `1` | How strongly it draws, from 0 (faint) to 1. Lower values quiet the middle band most, so text on top stays readable. |
| `fuji` | `boolean` | `true` | Draws Mount Fuji, small and moonlit on the far horizon. |
| `tokyoTower` | `boolean` | `true` | Draws Tokyo Tower, small and orange in the distance at the left. |
| `charset` | `CharsetName` | `"dots"` | Which glyphs draw the scene. See Charsets. |
| `chars` | `string` | `–` | A custom ramp from empty to dense, such as " .oO@". Wins over charset. |
| `colorMode` | `"mono" \| "truecolor" \| "ansi16" \| "duotone" \| "palette"` | `"truecolor"` | How glyphs are coloured. truecolor uses the scene's own colours, mono uses the theme ink or a phosphor, duotone runs tone through a ramp. "mono" when a phosphor is set. |
| `phosphor` | `"p1" \| "p3" \| "ibm" \| "blueprint"` | `–` | A CRT ink and glass for mono mode. Setting one switches colorMode to mono. |
| `ramp` | `RampName \| string[]` | `–` | In duotone mode, the colour ramp from dark to light. |
| `ansi` | `"vga" \| "xterm"` | `"vga"` | In ansi16 mode, which 16-colour table. |
| `grade` | `Grade` | `–` | Brightness, contrast, gamma and saturation applied to tones before glyphs are picked. |
| `invert` | `boolean` | `false` | Dense glyphs for dark tones instead of bright ones. |
| `threshold` | `number` | `0.5` | Braille and quadrants: the tone that lights a dot. |
| `edgeThreshold` | `number` | `0.22` | Edge charset: how strong a change in tone must be to draw - / \| or \. |
| `dither` | `"none" \| "bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer4"` | Ordered dithering between neighbouring dot sizes, which turns five dots into smooth tone like a print. |
| `background` | `"paper" \| "transparent"` | `"paper"` | "transparent" draws the glyphs only, over your own surface. |
| `fx` | `PostFx` | `–` | CRT finish: scanlines, bloom, curvature, glitch, flicker and vignette, each 0 to 1. |
| `interactive` | `boolean` | `–` | Accepted so any stage can pass it, and ignored: the city does not respond to the pointer. |
| `square` | `boolean` | `true for dots and other one-glyph charsets` | Cells as wide as they are tall, so the dots lay an even lattice. Braille and quadrants default to false, since they would stretch. |
| `cell` | `number` | `7` | Height of one glyph cell in CSS pixels, and its width too when square. |
| `speed` | `number` | `1` | How fast it moves. |
| `animate` | `boolean` | `true` | false stops the motion: a still frame if it starts off, the current frame if it was moving. |
| `fps` | `number` | `30` | Frame rate cap. |
| `stillTime` | `number` | `4` | The moment drawn when motion is off or reduced, in seconds. |
| `handle` | `RefObject<AsciiHandle \| null>` | `–` | Filled with a handle that reads back the current frame, for export to text, ANSI, SVG or PNG. |
| `paper` | `AsciiColor` | `–` | Paper behind the glyphs. By default the scene's night colour in truecolor, ansi16 and duotone, and the theme's paper (or the phosphor's) otherwise. |
| `fallback` | `ReactNode` | `–` | Shown without WebGL and until the first frame. By default a night gradient. |
| `className` | `string` | `–` | Size and position. The background fills this box. |

## Notes [#notes]

* It is decorative and hidden from assistive technology. Put real text on top of it, not inside it.
* With reduced motion turned on, it draws one still frame at `stillTime` and stops.
* It pauses when scrolled out of view or when the tab is hidden, and releases its WebGL context when far offscreen. Without WebGL it shows a night gradient.
* Nothing responds to the pointer, and there is no `interaction` prop.
* The whole scene is one GPU pass that raymarches the city for every sample, so its cost depends on the number of samples. `braille` samples eight times per cell; a larger `cell` makes it cheaper. See [Performance](/docs/engine/performance).