# Retro grid

A perspective grid floor scrolling towards a horizon under a striped, glowing sun, drawn as a dither.

> 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/retro-grid-demo.tsx" size="full" align="stretch" controls="retroGridControls">
  <RetroGridDemo />
</ComponentPreview>

## Installation [#installation]

<InstallBlock name="retro-grid" />

## Usage [#usage]

```tsx
import { RetroGrid } from "@/components/dithercn/retro-grid";

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

The floor is a grid seen from a low camera, scrolling slowly towards you. Lines stay about one cell wide at every depth and fade out where they would crowd closer than a few cells, so the horizon doesn't break into moiré. The sun sits half sunk behind the horizon, with slits through its lower half that thicken towards the ground and drift down. Grid squares keep their size against the box height, so a phone shows fewer columns, not thinner ones.

## Examples [#examples]

### Sunset [#sunset]

Four warm colours, from a deep violet paper through magenta to a pale gold sun. A bigger `sun` and `cell={4}` give it the chunky look of an old game.

<ComponentPreview src="examples/retro-grid-sunset.tsx" size="full" align="stretch">
  <RetroGridSunset />
</ComponentPreview>

### Without the sun [#without-the-sun]

`sun={0}` leaves only the glow along the horizon, which clears the sky for a headline.

<ComponentPreview src="examples/retro-grid-headline.tsx" size="lg" align="stretch">
  <RetroGridHeadline />
</ComponentPreview>

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `horizon` | `number` | `0.42` | Height of the horizon, from 0 (bottom) to 1 (top). |
| `sun` | `number` | `0.4` | Size of the sun as a share of the box height. 0 hides it. |
| `columns` | `number` | `12` | How many squares across the front of the floor in a 16:10 box. Narrower boxes show fewer. |
| `palette` | `[DitherColor, DitherColor, ...DitherColor[]]` | `Paper, two tints of --dither-ink, then --dither-ink` | Colours from paper to ink: palette names such as "blue", CSS variable names, or any CSS colour. |
| `matrix` | `"bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer4"` | The threshold pattern. See Dither engine. |
| `cell` | `number` | `--dither-cell` | Size of one dither cell in CSS pixels. |
| `speed` | `number` | `1` | How fast the floor scrolls and the sun's slits drift. |
| `animate` | `boolean` | `true` | false draws one still frame. |
| `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.
* 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 horizon line, a soft sun and a fade in CSS.