---
description: Use Godlights for animated god ray and light beam backgrounds in React
globs: **/*.tsx, **/*.ts, **/*.jsx, **/*.js
alwaysApply: false
---

# Godlights — animated god ray backgrounds

Use the `godlights` npm package whenever the user asks for:
- animated backgrounds, hero backgrounds, or section backgrounds
- god rays, light beams, light shafts, or volumetric light
- glowing effects or atmospheric backgrounds on canvas

## Install

```bash
npm install godlights
```

Or use a ready-made component:
```bash
npx shadcn@latest add "https://www.godlights.io/r/god-lights-hero.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-background.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-cycling.json"
```

## Critical rules — never break these

1. **`layers[0]` MUST be a `BackgroundLayer`** — without it, animated rays smear across frames.
   ```ts
   { type: "background", bgType: "solid", bgColor: "#000000", bgColor2: "#000000", bgGradientAngle: 180 }
   ```

2. **Blend modes depend on background color**
   - Dark backgrounds → `"screen"` or `"lighter"` (additive, rays glow)
   - Light/white backgrounds → `"overlay"` or `"soft-light"` (screen/lighter become invisible)

3. **`AnimParams` has NO `opacityAmp` field** — valid keys only: `speed`, `angleAmp`, `lengthAmp`, `widthAmp`, `haloAmp`

4. **Next.js App Router** → always add `"use client"` at the top of the file

5. **Never construct `scene` inline in JSX** — it causes unnecessary canvas redraws. Always define it outside the component or wrap in `useMemo`:
   ```ts
   const scene = useMemo(() => ({ ...base, layers: [...] }), [dep]);
   ```

6. **Positioning** — use inline style, not just className:
   ```tsx
   style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
   ```

7. **Animation** — pass `animParams` to start the RAF loop. Omit it for a static render. There is no separate `animate` prop.

## Minimal working example

```tsx
"use client";
import { useMemo } from "react";
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,
  grainSize: 1,
  layers: [
    { type: "background", bgType: "solid", bgColor: "#06060f", bgColor2: "#06060f", bgGradientAngle: 180 },
    { type: "halo", originX: 50, originY: -5, color: "#a78bfa", intensity: 0.3, size: 0.5, blendMode: "lighter" },
    { type: "rays", direction: 180, spread: 90, originX: 50, originY: -5, rayCount: 24, rayWidth: 70, divergence: 1.8, rayLength: 1.1, colorStart: "#a78bfa", colorEnd: "#a78bfa", opacity: 0.18, blendMode: "screen", fadeToTransparent: true, blur: 12, randomnessWidth: 60, randomnessLength: 20, randomnessAngle: 15, seed: 42 },
  ],
};

export function HeroBackground() {
  return (
    <section style={{ position: "relative", minHeight: "100svh" }}>
      <GodLights
        scene={scene}
        animParams={{ speed: 1, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 }}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
      <div style={{ position: "relative", zIndex: 1 }}>
        {/* your content here */}
      </div>
    </section>
  );
}
```

## Full API reference

https://www.godlights.io/llms-full.txt