# Glacier lagoon

Icebergs glowing blue-white on a glassy lagoon below a glacier and dark peaks, under a midnight sun sitting gold and rose on the horizon.

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

## Installation [#installation]

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

## Usage [#usage]

```tsx
import { GlacierLagoon } from "@/components/asciicn/glacier-lagoon";

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

The view looks across a glacier lagoon near midnight in high summer. The sun sits on the horizon right of centre, a white-gold disc inside a gold and rose glow that fades to night blue overhead. Dark peaks stand against the glow with alpenglow on their sunward crests, and the peaks right of centre sit farther back in haze. On the left a broad tongue of pale ice comes down between two peaks and ends in a deep blue calving face at the water, crossed by arcing bands and one dark stripe of moraine.

Six icebergs float on the lagoon, from a small block at the glacier's foot to a tall pinnacle on the right. Each is pale blue-white where the sun catches it and deep blue in shadow, with an aquamarine band at the waterline. The water is glassy. It mirrors the sky, the peaks and the glacier about the horizon and each berg about its own waterline, and small chips of brash ice are scattered across it.

Nothing moves fast, and the pointer does nothing. The bergs drift a few cells over several minutes, a band of low mist slides along the horizon, the clouds creep sideways, gold glints shimmer on the sun's path across the water, and the glow around the sun swells faintly.

It draws in `dots` by default on square 7px cells, about 200 columns across a 1440px screen, so the dots lay an even halftone lattice. Dot size carries brightness and, in `truecolor`, every dot takes its own colour. Even the darkest water and rock keep a faint dot, so every cell is painted. Set `square={false}` for charsets that need tall cells: `quadrants` gives a solid, saturated picture, `braille` a fine one, and `standard` a typed look. In `truecolor` it paints its own night sky, so it looks the same on light and dark pages. `mono` with a `phosphor` and `duotone` with a `ramp` read the same scene by brightness alone.

On wide boxes the glacier sits left and the sun right, with open sky and water between them for a headline. On tall boxes the layout narrows toward the centre, so the glacier, the sun and the nearest bergs stay in frame.

`intensity` dims the dots and their colours. Below 1 it also quiets an oval in the middle of the box, where a headline and buttons usually sit.

## Examples [#examples]

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

`intensity={0.7}` dims the dots and quiets the middle of the box, so a centred headline and two buttons read first.

```tsx title="examples/glacier-lagoon-hero.tsx"
import { GlacierLagoon } from "@/components/asciicn/glacier-lagoon";

export default function GlacierLagoonHero() {
  return (
    <section className="relative isolate flex size-full min-h-[480px] flex-col items-center justify-center gap-4 overflow-hidden bg-[#0a0b1c] px-6 text-center text-white">
      <GlacierLagoon intensity={0.7} className="absolute inset-0 -z-10" />
      <h3 className="max-w-xl text-3xl font-medium tracking-[-0.03em] text-balance sm:text-5xl">
        Ship before the ice moves
      </h3>
      <p className="max-w-sm text-sm text-pretty text-white/75">
        At 0.7 intensity the middle of the lagoon quiets down, so the headline
        reads first.
      </p>
      <div className="mt-2 flex flex-wrap items-center justify-center gap-3">
        <a
          href="#start"
          className="rounded-md bg-white px-4 py-2 text-sm font-medium text-[#0a0b1c] transition-colors hover:bg-white/85"
        >
          Get started
        </a>
        <a
          href="#docs"
          className="rounded-md border border-white/30 bg-white/5 px-4 py-2 text-sm font-medium text-white backdrop-blur-sm transition-colors hover:bg-white/15"
        >
          Read the docs
        </a>
      </div>
    </section>
  );
}
```

### In one ramp [#in-one-ramp]

`colorMode="duotone"` with `ramp="glacier"` reads the scene by brightness alone, from teal shadow to white ice. `mist={false}` keeps the horizon clear.

```tsx title="examples/glacier-lagoon-duotone.tsx"
import { GlacierLagoon } from "@/components/asciicn/glacier-lagoon";

// The glacier ramp reads the scene by brightness alone: teal shadow to white ice.
export default function GlacierLagoonDuotone() {
  return (
    <div className="relative isolate h-80 w-full max-w-2xl overflow-hidden rounded-xl border">
      <GlacierLagoon
        colorMode="duotone"
        ramp="glacier"
        mist={false}
        cell={9}
        className="absolute inset-0 -z-10"
      />
    </div>
  );
}
```

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `intensity` | `number` | `1` | How strongly the scene draws, from 0 to 1. Lower it to keep text on top readable. |
| `mist` | `boolean` | `true` | The band of low mist sliding across the water. |
| `square` | `boolean` | `true` | Cells as wide as they are tall, so the dots lay an even lattice. Turn it off for Braille, quadrants or text charsets. |
| `paper` | `AsciiColor` | `–` | The surface behind the glyphs. Without it, truecolor, ansi16 and duotone sit on a deep night blue; 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[]` | `"glacier"` | In duotone mode, the colour ramp from dark to light. The default runs from teal shadow to white ice. |
| `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. |
| `dither` | `"none" \| "bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer4"` | Ordered dithering between neighbouring glyph levels. The default mixes dot sizes so the sky's gradients stay smooth. |
| `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. With square cells it is also the width. |
| `speed` | `number` | `1` | How fast the mist, the clouds and the water move. |
| `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` | `0` | The moment drawn when motion is off or reduced, in seconds. Every moment shows the full scene. |
| `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.
* 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 flat gradient of the sky and the lagoon.
* The whole scene is one shader pass on the GPU. Water samples also draw the mirrored sky, peaks and glacier, so the lagoon costs about twice as much as the sky. See [Performance](/docs/engine/performance).