# New York

Manhattan at dusk across the East River: the Empire State Building's lit spire, the Chrysler crown and One World Trade Center against an amber-to-blue sky, with soft window light, broken reflections and a slow ferry.

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

## Installation [#installation]

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

## Usage [#usage]

```tsx
import { NewYork } from "@/components/asciicn/new-york";

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

The view looks west at Manhattan from Brooklyn just after sunset. The sky runs from amber on the horizon through coral and violet to a deep blue that is almost the paper, with the afterglow low on the west side, behind the rooftops. The landmarks stand clear of the middle, where a headline goes: One World Trade Center to the west, its glass catching the afterglow on one side, and the Empire State Building to the east, its top floors floodlit gold under a lit crown, mast and antenna, with the Chrysler Building's arched crown outlined in white beside it. Between them the low Village and three rows of towers behind fade into the dusk haze, each row paler, flatter and smaller in its dots than the one in front. On a tall phone the landmarks shrink a little so all three stay beside the headline.

Windows light the skyline in warm lamp light, amber and a few cool office tubes, varied per tower and per floor. The river mirrors the city in long, broken streaks, the landmarks' lights run down it in columns to the bottom of the frame, and a glitter path lies under the afterglow.

The buildings never move. A few windows fade on or off at a time, each on its own clock of one to two minutes. The reflections shimmer, the spire lights breathe, a few stars twinkle, thin clouds drift and a ferry crosses in about three minutes. Nothing follows the pointer.

It draws in `dots` on square 7px cells by default, about 200 columns across a wide screen, so the dots lay an even halftone lattice and dot size carries tone: the deep sky and the dark facades are the smallest dots in a colour close to the paper, mid tones are small and medium dots, and only the lit crowns, windows and the afterglow get the large ones. In `truecolor`, the default, every dot takes its own colour on the scene's dusk navy, so it looks the same on light and dark pages. `braille` and `quadrants` want `square={false}`, and draw only the brighter parts, as outlines and lights. `mono` with a `phosphor` and `duotone` with a `ramp` read the same scene by tone alone.

## Examples [#examples]

### Hero [#hero]

`intensity={0.6}` dims the city so a centred headline and buttons read first, and the skyline still shows around them.

```tsx title="examples/new-york-hero.tsx"
import { NewYork } from "@/components/asciicn/new-york";
import { Button } from "@/components/ui/button";

export default function NewYorkHero() {
  return (
    <section className="relative isolate flex size-full min-h-[420px] flex-col items-center justify-center gap-4 px-6 text-center text-white">
      <NewYork intensity={0.6} className="absolute inset-0 -z-10" />
      <h3 className="max-w-lg text-3xl font-medium tracking-[-0.03em] text-balance sm:text-5xl">
        Ship before the lights come on
      </h3>
      <p className="max-w-sm text-sm text-pretty text-white/75">
        At 0.6 intensity the skyline steps back and the headline reads first.
      </p>
      <div className="mt-1 flex gap-2">
        <Button size="sm" className="bg-white text-black hover:bg-white/90">
          Get started
        </Button>
        <Button
          size="sm"
          variant="outline"
          className="border-white/30 bg-black/20 text-white hover:bg-white/10 hover:text-white"
        >
          Read the docs
        </Button>
      </div>
    </section>
  );
}
```

### On a green monitor [#on-a-green-monitor]

`colorMode="mono"` with `phosphor="p1"` draws every dot in one green, and `fx` scanlines, bloom and vignette finish the look.

```tsx title="examples/new-york-phosphor.tsx"
import { NewYork } from "@/components/asciicn/new-york";

// One green phosphor, the halftone dots and a CRT finish: Manhattan on a surveillance monitor.
export default function NewYorkPhosphor() {
  return (
    <div className="relative isolate flex h-80 w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-[#0f3a1a] bg-[#020a04] font-mono">
      <NewYork
        colorMode="mono"
        phosphor="p1"
        windows={0.65}
        fx={{ bloom: 0.5, scanlines: 0.4, vignette: 0.45 }}
        className="absolute inset-0 -z-10"
      />
      <div className="flex items-center justify-between border-b border-[#0f3a1a] bg-[#020a04]/80 px-3 py-1.5 text-[11px] text-[#33ff66]/70">
        <span>east-river.cam</span>
        <span>23:40 · 40.70N 73.99W</span>
      </div>
    </div>
  );
}
```

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intensity` | `number` | `1` | How strongly the city draws, from 0 to 1. Lower it to keep text on top readable. |
| `windows` | `number` | `0.55` | Share of windows lit across the skyline, from 0 (dark) to 1. A few windows change at a time, each on its own slow clock. |
| `ferry` | `boolean` | `true` | The ferry crossing the river, once every three minutes or so. |
| `square` | `boolean` | `true` | Cells as wide as they are tall, so the dots lay an even halftone lattice. false uses the font's narrow cells. |
| `paper` | `AsciiColor` | `–` | The surface behind the glyphs. Without it, truecolor, ansi16 and duotone sit on the scene's dusk navy; mono and palette use the theme's paper or the phosphor's. |
| `fallback` | `ReactNode` | `a gradient` | Shown without WebGL and until the first frame. |
| `charset` | `CharsetName` | `"dots"` | Which glyphs draw the tones. 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 paints the scene's own colours; mono uses one ink or a phosphor; duotone runs tone through a ramp. |
| `phosphor` | `"p1" \| "p3" \| "ibm" \| "blueprint"` | `–` | A CRT ink and glass. Setting one switches the default colour mode 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"` | `"none"` | Ordered dithering between neighbouring glyph levels. |
| `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. |
| `cell` | `number` | `7` | Height of one glyph cell in CSS pixels. |
| `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` | `30` | 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. |
| `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.
* The buildings never move and nothing reacts to the pointer. Only window lights, the spire lights, stars, clouds, the reflections and the ferry change.
* With reduced motion turned on, it draws one still frame at `stillTime`, with the ferry on the river, 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 gradient in the same colours.
* The whole city is one shader pass on the GPU. The river reads the skyline three times to mirror it and stretch its lights, so a water cell costs about three sky cells. `braille` samples eight times per cell, so it costs the most. See [Performance](/docs/engine/performance).