# Beams

God rays: shafts of light from a point or an edge that sweep slowly and fade with distance.

> 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/beams-demo.tsx" size="full" align="stretch" controls="beamsControls">
  <BeamsDemo />
</ComponentPreview>

## Installation [#installation]

<InstallBlock name="beams" />

## Usage [#usage]

```tsx
import { Beams } from "@/components/dithercn/beams";

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

Light comes from `origin` and spreads in a cone around `angle`. The rays are noise around the origin, so they widen with distance like real shafts of light, and dust drifting through them breaks them up along their length. The whole cone sways back and forth by `sweep` degrees over about a minute.

## Examples [#examples]

### From the top edge [#from-the-top-edge]

An origin far above the box gives nearly parallel rays, like light through a high window. Brightness fades from where the light enters the box, not from the far origin.

<ComponentPreview src="examples/beams-edge.tsx" size="full" align="stretch">
  <BeamsEdge />
</ComponentPreview>

### Spotlight over a headline [#spotlight-over-a-headline]

A narrow cone from just above the centre, through a four-colour palette, with a short `reach` so the text at the bottom sits in the dark.

<ComponentPreview src="examples/beams-headline.tsx" size="lg" align="stretch">
  <BeamsHeadline />
</ComponentPreview>

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `origin` | `[x: number, y: number]` | `[0.18, -0.12]` | Where the light comes from, as fractions of the box from the top left. Values outside 0 to 1 put it out of frame. |
| `angle` | `number` | `160` | Direction the light points, in degrees as in CSS: 180 is straight down. |
| `spread` | `number` | `80` | Width of the cone in degrees. |
| `rays` | `number` | `9` | Roughly how many separate rays. |
| `sweep` | `number` | `6` | How far the cone sways each way, in degrees. 0 holds it still. |
| `reach` | `number` | `1` | How far the light reaches from where it enters the box, as a share of the box diagonal. |
| `palette` | `[DitherColor, DitherColor, ...DitherColor[]]` | `["--dither-paper", "--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. |
| `levels` | `number` | `All the matrix can draw` | Tones before dithering. |
| `cell` | `number` | `--dither-cell` | Size of one dither cell in CSS pixels. |
| `speed` | `number` | `1` | How fast the rays drift and sway. |
| `animate` | `boolean` | `true` | false draws one still frame. |
| `className` | `string` | `–` | Size and position. The light fills this box. |

## Notes [#notes]

* The light 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 soft CSS cone.