# Rio de Janeiro

Rio de Janeiro at dusk from the water in dots: Sugarloaf beside Morro da Urca with one cable car crossing, Christ the Redeemer pale on Corcovado, and the lamps of Copacabana curving along the shore under a gold to violet 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/rio.json](https://asciicn.dev/r/rio.json), under `files[].content`.

## Installation [#installation]

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

## Usage [#usage]

```tsx
import { Rio } from "@/components/asciicn/rio";

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

The whole frame is painted in halftone dots. Each dot takes its own colour, and its size carries the light: the biggest dots gather in the gold afterglow on the horizon and its reflection, middle dots run through the rose and violet sky, and the deep sky and the shadowed mountains fall to the smallest dots, close to the paper.

The sun has just set between the mountains. Sugarloaf rises out of the bay on the right as a great dark dome that leans towards the lower, forested Morro da Urca beside it. Its flank towards the afterglow catches a rose light and a lit rim, while the face towards you stays in shadow. A cable runs from the top of Urca to the top of Sugarloaf, a fine dark line against the glow, and one cable car's light crosses it: it waits about 12 seconds at each station, then takes about half a minute to cross. On the left, Corcovado climbs out of the Tijuca range, hazier and paler because it stands farther off, to a granite needle with Christ the Redeemer on the summit, small and lit pale by floodlights. Below it, the lamps of Copacabana curve along the shore in a crescent in front of a low wall of apartment blocks, and homes are lit on the lower slopes.

The bay mirrors all of it, darker and cooler, broken into ripples that widen towards you. Under the afterglow runs a long gold reflection, and the beach lamps draw short warm lines down into the water.

Motion is slow: the cable car crosses, the reflections shimmer as the ripples drift, the lamps along the beach twinkle gently, a few windows turn on or off every couple of minutes, thin clouds drift and stars twinkle faintly. The pointer does nothing.

On wide boxes Corcovado and Sugarloaf frame the middle, so the sky over the afterglow stays calm for a headline. On tall boxes the scene is drawn smaller and lower, so both peaks stay in view beneath the headline.

It draws in `dots` by default on square 7px cells, so the dots lie in an even lattice, about 200 across a 1440px screen. `square={false}` returns to the usual text cells, twice as tall as wide. Other ramp charsets such as `standard` or `dense` read the same tones as typed glyphs. `braille` and `quadrants` light a dot only above half tone, so they keep the lit parts (the afterglow, the lights and the reflection) and leave the dark sky and mountains empty. In `truecolor`, the default, the scene paints its own dusk paper in both themes. `duotone` with a `ramp` and `mono` with a `phosphor` read the same scene by tone alone.

`intensity` dims the colours in step and shrinks the dots more gently, so the shapes keep their place behind text.

## Examples [#examples]

### Hero [#hero]

`intensity={0.85}` quiets the scene a little behind a centred headline and two buttons. Corcovado and Sugarloaf stand either side of the text on wide screens and below it on phones.

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

export default function RioHero() {
  return (
    <section className="relative isolate flex size-full min-h-[420px] flex-col items-center justify-center gap-5 px-6 text-center text-white">
      <Rio intensity={0.85} className="absolute inset-0 -z-10" />
      <h3 className="max-w-xl text-3xl font-medium tracking-[-0.03em] text-balance sm:text-5xl">
        Launch at golden hour
      </h3>
      <p className="max-w-md text-sm text-pretty text-white/75 sm:text-base">
        A dusk over Guanabara Bay for your landing page, with Sugarloaf to the
        right of the 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 text-sm font-medium text-[#1a1206]"
        >
          Get started
        </a>
        <a
          href="#docs"
          className="rounded-full border border-white/25 bg-white/5 px-5 py-2 text-sm font-medium text-white backdrop-blur-sm"
        >
          Read the docs
        </a>
      </div>
    </section>
  );
}
```

### Gold print [#gold-print]

`colorMode="duotone"` runs the tones through the `sodium` ramp, gold on night blue, and `cell={5}` packs finer dots into a small card.

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

// Gold duotone on finer dots: the bay as a single-ink print in a card.
export default function RioDuotone() {
  return (
    <div className="relative isolate flex h-80 w-full max-w-2xl flex-col justify-end overflow-hidden rounded-xl border border-white/10 p-5">
      <Rio colorMode="duotone" cell={5} className="absolute inset-0 -z-10" />
      <p className="font-mono text-xs text-[#fcb442]/80">
        22.95°S 43.16°W · Baía de Guanabara
      </p>
    </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. |
| `cableCar` | `boolean` | `true` | The cable from Urca to Sugarloaf, its two stations and the car crossing it. |
| `paper` | `AsciiColor` | `–` | The surface behind the glyphs. Without it, truecolor, ansi16 and duotone sit on a dusk indigo; mono and palette use the theme's paper or the phosphor's. |
| `square` | `boolean` | `true for dots` | Cells as wide as they are tall, so the dots lie in an even lattice. Off by default for braille and quadrants, which would stretch. |
| `fallback` | `ReactNode` | `a gradient` | Shown without WebGL and until the first frame: the dusk as a flat gradient. |
| `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[]` | `"sodium"` | 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. Lower it to bring the dusk sky and the mountains back. |
| `edgeThreshold` | `number` | `0.22` | Edge charset: how strong a change in tone must be to draw - / \| or \. |
| `dither` | `"none" \| "bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"blue-noise" for dots` | Blends neighbouring dot sizes so the sky's gradient reads smooth. Blue noise for dots, braille and quadrants; none for other charsets and custom chars. |
| `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` | `12` | 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.
* It ignores the pointer: no parallax and no hover effect.
* With reduced motion turned on, it draws one still frame at `stillTime` and stops. The default, 12 seconds, catches the cable car halfway across.
* 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 the dusk as a flat gradient.
* The whole city is one shader pass on the GPU, one sample per dot. See [Performance](/docs/engine/performance).