# Ocean waves

A moonlit sea in glyphs, with swells rolling in, foam that breaks into lighter glyphs on the crests, a glittering moon path and slow clouds.

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

## Installation [#installation]

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

## Usage [#usage]

```tsx
import { OceanWaves } from "@/components/asciicn/ocean-waves";

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

The view is out to sea on a clear night. Long swells roll in slowly toward you, small and crowded at the horizon and wide near the bottom of the box, with a run of `~` along every crest. Where a crest spills it comes apart into foam: `*`, `'`, `.` and `` ` ``, lighter the further it breaks. A full moon hangs over the water and lays a path of glints that shimmer as the waves pass through it, each glint on its own slow beat. Thin clouds drift across the sky, lit at their edges near the moon.

`swell` sets the size of the swells, from a flat calm at 0 to heavy seas at 1. `wind` adds chop on top, brings foam to more of the crests and moves the clouds faster. Turn `moon` off for a dark night with only starlight and foam.

It draws in `standard` glyphs and `truecolor` by default. The charset sets the glyphs for the sky, clouds and water shading. With a ramp charset the crests, foam and glints are drawn as line glyphs on top; `braille` and `quadrants` draw everything from their own sub-cell dots. In `mono` mode every glyph takes the ink, or a `phosphor`. `intensity` thins every glyph at once. Lower it to around 0.5 under a headline.

## Examples [#examples]

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

`intensity={0.5}` with a low swell and little wind keeps the sea quiet behind the text.

```tsx title="examples/ocean-waves-headline.tsx"
import { OceanWaves } from "@/components/asciicn/ocean-waves";

// The sea behind a headline, dimmed so the text on top stays readable.
export default function OceanWavesHeadline() {
  return (
    <section className="relative isolate flex size-full flex-col items-center justify-start gap-3 px-6 pt-14 text-center">
      <OceanWaves
        intensity={0.5}
        swell={0.4}
        wind={0.2}
        className="absolute inset-0 -z-10"
      />
      <h3 className="max-w-md text-3xl font-medium tracking-[-0.03em] text-balance sm:text-4xl">
        Calm water, steady hands
      </h3>
      <p className="text-muted-foreground max-w-sm text-sm text-pretty">
        Lower the intensity and the swell, and the sea settles behind your copy.
      </p>
    </section>
  );
}
```

### Gale on a blueprint phosphor [#gale-on-a-blueprint-phosphor]

`moon={false}`, `swell={1}` and `wind={0.9}`: a moonless night with foam on nearly every crest, in cyan on dark glass with a light CRT finish.

```tsx title="examples/ocean-waves-storm.tsx"
import { OceanWaves } from "@/components/asciicn/ocean-waves";

// A dark night in a gale: no moon, heavy swell, foam on every crest.
export default function OceanWavesStorm() {
  return (
    <OceanWaves
      moon={false}
      swell={1}
      wind={0.9}
      phosphor="blueprint"
      fx={{ scanlines: 0.3, vignette: 0.45 }}
      className="absolute inset-0"
    />
  );
}
```

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `swell` | `number` | `0.6` | How big the rolling swells are, from 0 (a flat calm) to 1 (heavy seas). |
| `wind` | `number` | `0.4` | How hard the wind blows, from 0 to 1: more chop, more foam on the crests, faster clouds. |
| `moon` | `boolean` | `true` | Show the moon and its glittering path on the water. |
| `intensity` | `number` | `1` | How much of the scene shows, from 0 (empty paper) to 1. Lower it under text. |
| `charset` | `CharsetName` | `"standard"` | Which glyphs draw the sky, clouds and water. See Charsets. Ramps also get line-glyph crests and foam. |
| `chars` | `string` | `–` | A custom ramp from empty to dense, such as " .oO@". Wins over charset. |
| `colorMode` | `"truecolor" \| "mono"` | `"truecolor", or "mono" with a phosphor` | truecolor keeps the night's colours. mono draws every glyph in the ink or phosphor. |
| `phosphor` | `"p1" \| "p3" \| "ibm" \| "blueprint"` | `–` | A CRT ink and glass that replace the ink and paper. |
| `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` | `12` | Height of one glyph cell in CSS pixels. |
| `speed` | `number` | `1` | How fast the swells roll and the clouds drift. |
| `animate` | `boolean` | `true` | false holds one still frame. |
| `stillTime` | `number` | `6` | 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 scene 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, so moving the mouse over it changes nothing.
* With reduced motion turned on, it draws one still frame at `stillTime` and stops.
* It draws on the CPU at up to 30 fps and pauses when scrolled out of view or when the tab is hidden. Far out the swells fade into a calm sheen before they crowd closer than a glyph row, so the horizon stays steady instead of shimmering.