# Aurora

Curtains of light that fold, sway and shimmer, drawn as a dither, with knobs for colour, rays, tilt and drift.

> 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 dithercn agent skill, for building any dither on the engine, is at [/.well-known/agent-skills/dithercn/SKILL.md](/.well-known/agent-skills/dithercn/SKILL.md).

<ComponentPreview src="examples/aurora-demo.tsx" size="full" align="stretch" controls="auroraControls">
  <AuroraDemo />
</ComponentPreview>

## Installation [#installation]

<InstallBlock name="aurora" />

## Usage [#usage]

```tsx
import { Aurora } from "@/components/dithercn/aurora";

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

Each curtain has a bright lower edge that folds slowly, with rays that fade as they rise. Further curtains hang higher and dimmer. `height` sets where the lowest edge hangs, so you can keep the area under it clear for text.

The props group into three jobs:

* Shape: `curtains`, `height`, `spread`, `sway`, `turbulence`, `rays`, `length`.
* Light and colour: `color` for the edges, `tipColor` for the tops of the rays, `background`, `glow`, `intensity`, `shimmer`. Pass `palette` to set every tone yourself.
* Placement and motion: `tilt`, `scale`, `drift`, `direction`, `mask`, plus the engine's `speed`, `cell` and `matrix`.

## Examples [#examples]

### Above a headline [#above-a-headline]

Raising `height` lifts the curtains off the lower third, where the headline sits on clean paper. A `tipColor` of `"blue"` shifts the tops of the rays to a second, cooler hue, and `mask="edges"` fades the sides.

<ComponentPreview src="examples/aurora-hero.tsx" size="lg" align="stretch">
  <AuroraHero />
</ComponentPreview>

### Northern lights [#northern-lights]

Your own colours turn it into the real thing: green edges, violet tips and a night-sky `background`. Four curtains, longer rays, a slight `tilt` and a little `drift` give it depth.

<ComponentPreview src="examples/aurora-borealis.tsx" size="lg" align="stretch">
  <AuroraBorealis />
</ComponentPreview>

### Hanging over a call to action [#hanging-over-a-call-to-action]

`direction="down"` flips the curtains so the rays fall from the top and the button sits on clear paper below. Few broad `rays` and 4px cells give it a coarser, poster-like grain.

<ComponentPreview src="examples/aurora-cta.tsx" size="lg" align="stretch">
  <AuroraCta />
</ComponentPreview>

### Still, in a banner [#still-in-a-banner]

With `animate={false}` it draws one frame. `stillTime` picks which moment, so you can choose a shape you like.

<ComponentPreview src="examples/aurora-banner.tsx">
  <AuroraBanner />
</ComponentPreview>

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `DitherColor` | `"--dither-ink"` | The bright lower edge of each curtain. |
| `tipColor` | `DitherColor` | `color` | The faint tops of the rays. Set a second colour for a two-tone sky. |
| `background` | `DitherColor` | `"--dither-paper"` | The sky behind. |
| `curtains` | `number` | `3` | How many curtains, from 1 to 6. Each one hangs higher and dimmer. |
| `height` | `number` | `0.42` | Where the lowest bright edge hangs, from 0 (bottom) to 1 (top). |
| `spread` | `number` | `0.11` | Vertical gap between curtains, from 0 to 0.3. |
| `sway` | `number` | `1` | How far the edges fold. 0 is straight, 3 is deep folds. |
| `turbulence` | `number` | `0.6` | Fine ripples along each edge, from 0 to 2. |
| `rays` | `number` | `8` | How many rays fit across. 2 gives broad bands, 20 fine needles. |
| `length` | `number` | `0.45` | How far the rays reach up, from 0 to 1. |
| `glow` | `number` | `0.9` | Brightness of the line along each edge, from 0 to 2. |
| `intensity` | `number` | `0.95` | Brightness of the curtains, from 0 to 1. |
| `shimmer` | `number` | `0.2` | A slow brightness ripple, from 0 to 1. |
| `scale` | `number` | `1` | Horizontal zoom. Higher values fit more folds across. |
| `tilt` | `number` | `0` | Tilt of the curtains in degrees, from -45 to 45. |
| `drift` | `number` | `0` | Sideways travel, from -2 (left) to 2 (right). |
| `direction` | `"up" \| "down"` | `"up"` | "down" flips it so the rays hang from a bright top edge. |
| `mask` | `"none" \| "top" \| "bottom" \| "edges"` | `"none"` | Fades it to paper where your text sits. |
| `palette` | `[DitherColor, DitherColor, ...DitherColor[]]` | `Built from the colour props` | Takes over the colours: paper first, brightest last. Palette names, CSS variable names or any CSS colour. |
| `matrix` | `"bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer8"` | The threshold pattern. See Dither engine. |
| `levels` | `number` | `All the matrix can draw` | Tones the field snaps to before dithering. Low values give hard steps. |
| `cell` | `number` | `--dither-cell` | Size of one dither cell in CSS pixels. |
| `speed` | `number` | `1` | How fast it moves. |
| `animate` | `boolean` | `true` | false draws one still frame. |
| `stillTime` | `number` | `0` | The moment drawn when motion is off or reduced, in seconds. |
| `className` | `string` | `u2013` | 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 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 CSS approximation in the same colours.
* It costs one small draw per frame at 30 fps, at one pixel per dither cell. More `curtains` cost a little more per pixel. See [Performance](/docs/engine/performance).