# Aurora

> Soft northern-lights background: folding light curtains drawn in a shader with premultiplied alpha, so it glows on dark and washes on light.

- **Slug:** `aurora` · **Category:** effects · **Status:** beta
- **Import:** `import { Aurora } from "@kura-ui/react/aurora";`
- **Docs:** https://kuro.abstergo.fyi/components/aurora
- **Registry item:** https://kuro.abstergo.fyi/r/aurora.json
- **Tags:** aurora, northern-lights, background, webgl, shader, hero, night, ambient

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/aurora.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add aurora
# npm package
npm install @kura-ui/react
```

## When to use

- A sign-in, landing or 'welcome back' screen that should feel calm and a little magical.
- A night-themed hero or a header band above an agent dashboard.
- A background that must sit on top of an existing surface colour (it is transparent where there is no light).

## When not to use

- A colourful blob background filling the whole area — use mesh-gradient.
- Showing that an agent is busy — use border-beam or thinking-indicator.
- A voice agent's presence — use agent-orb.
- Behind dense UI or long text: the curtains move; keep content short and centred.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `colors` | `"signal" \| "polar" \| "ember" \| "mist" \| readonly [string, string, string]` | `"signal"` | no | A preset, or three CSS colours `[lower edge, middle, upper fringe]`. signal uses the theme accent; polar is classic green-teal-blue. |
| `intensity` | `number` | `0.8` | no | Brightness of the curtains, 0–1. |
| `speed` | `number` | `1` | no | Animation speed multiplier. 0 renders a still frame. |
| `stars` | `boolean` | `true` | no | Twinkling stars behind the curtains. Only drawn when the background is dark. |
| `paused` | `boolean` | `false` | no | Freeze the animation on the current frame. |
| `maxDpr` | `number` | `1.5` | no | Device-pixel-ratio cap. |
| `children` | `React.ReactNode` | — | no | Content rendered on top, in normal flow. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Aurora** (`data-slot="aurora"`) — Root container (`relative isolate overflow-hidden`). Give it a size and a background colour. `data-state` = animating | still.
- **ShaderCanvas** (`data-slot="aurora-canvas"`) — Transparent WebGL layer behind the children (aria-hidden).
- **Fallback** (`data-slot="aurora-fallback"`) — Blurred CSS radial gradients shown when WebGL2 is unavailable.

## Accessibility

- Decorative and aria-hidden; children keep their semantics.
- The curtains sit mostly in the lower half; place text near the top or centre and check contrast in both themes.
- Reduced motion: Renders one still frame (no drift, no twinkle). Theme changes redraw it.

## Notes for agents

- The canvas is transparent: set a background on the root (`bg-kura-canvas`, `bg-kura-surface-sunken`) — the aurora is light added on top of it.
- Give the root a height (`h-72`, `min-h-96`, `aspect-video`).
- Lift children above the canvas automatically (they are in flow); lift them above a `<Grain />` overlay with `relative z-10`.
- On light themes the curtains render as a deeper watercolour wash; check both themes.

## Examples

### Aurora on the canvas colour (minimal)

Give it a size and a background; the signal preset follows the theme.

```tsx
import { Aurora } from "@kura-ui/react/aurora";

export function AuroraMinimal() {
  return <Aurora className="h-72 w-full rounded-kura-xl bg-kura-canvas shadow-kura-sm" />;
}
```

### Presets, intensity, stars (full)

Every preset, intensity, stars and pause.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Aurora, type AuroraPreset } from "@kura-ui/react/aurora";

const presets: AuroraPreset[] = ["signal", "polar", "ember", "mist"];

export function AuroraFull() {
  const [preset, setPreset] = React.useState<AuroraPreset>("polar");
  const [intensity, setIntensity] = React.useState(0.85);
  const [stars, setStars] = React.useState(true);
  const [paused, setPaused] = React.useState(false);
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <Aurora
        colors={preset}
        intensity={intensity}
        stars={stars}
        paused={paused}
        className="aspect-[16/9] w-full rounded-kura-xl bg-kura-surface-sunken shadow-kura-md"
      />
      <div className="flex flex-wrap items-center gap-1.5">
        {presets.map((p) => (
          <Button
            key={p}
            size="sm"
            variant={p === preset ? "secondary" : "ghost"}
            aria-pressed={p === preset}
            onClick={() => setPreset(p)}
            className="capitalize"
          >
            {p}
          </Button>
        ))}
        <span className="ml-auto flex gap-1.5">
          <Button
            size="sm"
            variant="ghost"
            aria-pressed={stars}
            onClick={() => setStars((s) => !s)}
          >
            Stars {stars ? "on" : "off"}
          </Button>
          <Button size="sm" variant="ghost" onClick={() => setPaused((p) => !p)}>
            {paused ? "Play" : "Pause"}
          </Button>
        </span>
      </div>
      <label className="flex max-w-xs flex-col gap-1.5 text-kura-fg-muted text-xs">
        Intensity {intensity.toFixed(2)}
        <input
          type="range"
          min={0}
          max={1}
          step={0.05}
          value={intensity}
          onChange={(e) => setIntensity(Number(e.target.value))}
          className="accent-kura-accent"
        />
      </label>
    </div>
  );
}
```

### Sign-in hero (composition)

Headline and Buttons over the aurora, finished with Grain.

```tsx
import { Button } from "@kura-ui/react/button";
import { Grain } from "@kura-ui/react/grain";
import { Aurora } from "@kura-ui/react/aurora";

export function AuroraSignIn() {
  return (
    <Aurora
      intensity={0.7}
      className="flex min-h-96 w-full flex-col items-center justify-start gap-3 rounded-kura-2xl bg-kura-canvas px-6 pt-14 text-center shadow-kura-md"
    >
      <h2 className="relative z-10 text-balance font-medium text-3xl text-kura-fg tracking-tight">
        Your agents worked through the night.
      </h2>
      <p className="relative z-10 max-w-sm text-kura-fg-muted text-sm leading-relaxed">
        Sign in to review 14 finished tasks and 2 waiting for approval.
      </p>
      <div className="relative z-10 mt-2 flex gap-2">
        <Button>Sign in</Button>
        <Button variant="secondary">Create account</Button>
      </div>
      <Grain opacity={0.18} />
    </Aurora>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `kura-shader-color`, `shader-canvas`, `use-reduced-motion`, `utils`
- Related: `mesh-gradient`, `grain`, `particle-field`, `shader-canvas`