# Afterglow

> Light runs through a card the moment something works: it rises from the button you pressed, the old content dissolves into the new behind it, and what changed catches the light.

When a scene runs, a payout goes out or a menu is published, most apps swap the card’s text and maybe show a toast, and the moment the thing actually worked passes without anyone noticing what changed. Afterglow wraps the element and gives that moment a light of its own. Call play with your state change: a band of light leaves the control you pressed, warm ahead and clear blue behind a white-hot front, and spreads across the element in its own shape, a horizon rising through a card, a streak along a pill, a ring from the middle of a round tile. Your update runs at once, under a still copy of the old content, and the light dissolves that copy grain by grain just behind its bright line: each old value turns into the new one in its own place as the light passes over it, and anything that didn’t change never moves. As it clears, only the text that changed catches the light, a glint rippling out from where you pressed, so the person sees at a glance what’s different. Fine dust twinkles in the wake, and the edge keeps an iridescent glow for a moment, the far side last.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/afterglow.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/afterglow
- Registry item (source): https://hairlineui.com/r/afterglow.json

## Usage

```tsx
import { Afterglow, type AfterglowHandle } from "@/components/afterglow";

const glow = useRef<AfterglowHandle>(null);

async function run() {
  await runScene();
  glow.current?.play(() => setDone(true));
}

<Afterglow ref={glow}>
  <SceneCard done={done} onRun={run} />
</Afterglow>
```

## Running a scene from a smart-home app

Your own call stays in charge: show your pending state while it runs, and hand the result to play so it lands under the light.

```tsx
"use client";
import { useRef, useState } from "react";
import { Afterglow, type AfterglowHandle } from "@/components/afterglow";

export function SceneCard({ scene }: { scene: { id: string; name: string } }) {
  const glow = useRef<AfterglowHandle>(null);
  const [state, setState] = useState<{ lights: string; door: string } | null>(null);
  const [running, setRunning] = useState(false);

  async function run() {
    setRunning(true);
    try {
      const res = await fetch(`/api/scenes/${scene.id}/run`, { method: "POST" });
      const next = await res.json();
      await glow.current?.play(() => {
        setState(next);
        setRunning(false);
      });
    } catch {
      setRunning(false);
    }
  }

  return (
    <Afterglow ref={glow}>
      <div className="w-72 rounded-3xl border bg-card p-4">
        <h3>{scene.name}</h3>
        <p>Lights: {state?.lights ?? "6 on"}</p>
        <p>Front door: {state?.door ?? "Unlocked"}</p>
        <button onClick={run} disabled={running}>{state ? "Done" : running ? "Starting…" : "Run scene"}</button>
      </div>
    </Afterglow>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ref` | `Ref<AfterglowHandle>` | – | Gives you play(update?, { origin? }), which calls update at once under a copy of the old content, runs the light that dissolves it, and resolves when the light has gone. |
| `children` | `ReactNode` | – | One element: a card, a pill, a tile, a row. The light takes its size and corner radius. |
| `origin` | `"press" \| "center" \| "top" \| "bottom" \| "left" \| "right" \| { x: number; y: number }` | `"press"` | Where the light starts. "press" is the control last pressed inside (the exact point when the whole element is the control), else the focused one, else the bottom edge. x and y are 0 to 1. |
| `colors` | `[string, string, string]` | `["#ffb347", "#ff4f8b", "#3d8bff"]` | The warm light ahead of the front, its fringe and the clear light behind. Any CSS colours. |
| `glint` | `boolean` | `true` | Let the text that changed catch the light as the content clears. |
| `onFinish` | `() => void` | – | Called when the light has gone. |

## States

- **rise**: The front leaves the pressed control and covers about two thirds of its way in 320ms, then slows; the whole sweep takes 1.1s and the band fades over its last half.
- **dissolve**: Your update runs straight away under a still copy of the old content. The copy stays solid ahead of the light and dissolves through a fine grain over the stretch just behind its bright line, so the change travels with the light. Inside the element everything softens to a 4px blur over 240ms and clears over 700ms; the element’s own edge never blurs.
- **glint**: Text that differs after the update takes a band of the light’s colours once, over 820ms, starting as soon as the dissolve has finished over it and running the way the light travelled.
- **afterglow**: Dust twinkles in the wake and fades over about 700ms; the edge glows in turn as the front reaches it and fades over about 800ms. Everything is gone at 2s.
- **again**: Calling play while the light runs ends the current one at once (its copy of the old content goes) and starts over.
- **reduced motion**: No light, no blur and no glint: the update runs straight away.

## What it handles

A card that just swaps its text when an action succeeds gives no moment for it, and doesn’t say which of its values are new.

- **One call**: play(update) on a ref; your state, buttons and API stay as they are.
- **Dissolves in place**: The old content breaks up into the new just behind the light, never as a hard swap.
- **Its own shape**: It takes the element’s corner radius and runs as a horizon, a streak or a ring.
- **From your press**: It leaves the control that was pressed or focused, or any edge you name.
- **What changed**: Only text that’s different after the update catches the light, nearest first.
- **Light and dark**: Light is added on dark surfaces and laid on as colour on light ones.

## Replaces

success animation, success toast, confetti, shimmer effect, done state, changed field highlight

## Where it fits

- **Smart home and IoT**: A scene that ran, a lock that locked, a thermostat that took the new setting.
- **Publishing**: A page, a menu or a release going live, with the fields that changed lit up.
- **Payments and payouts**: Money sent or received, on the card or pill that shows it.
- **Habits and goals**: A check-in, a streak kept, a goal reached on a round tile or a ring.

## Notes

- The light is one WebGL 2 shader on a canvas laid over the element, made the first time a pointer comes near or play is called and kept until unmount. Each frame is a few uniforms and one triangle; nothing runs between plays. Without WebGL the content still blurs, changes and glints.
- The old content is a deep copy of the element laid exactly over it (inert, ids and names removed, hidden from screen readers), dissolved with a CSS mask: a radial edge that follows the light, intersected with a 64px grain tile. Where nothing changed the copy and the element are identical, so the dissolve is invisible there. The soft blur goes on the children of both, each on its own layer, so the box, its border and its background stay crisp.
- Changed text is found by comparing every text-only element before and after the update, by its place in the tree. Text hidden from screen readers (TextMorph letters, digit strips) and screen-reader-only text are skipped. Pass glint={false} to switch it off.
- The canvas is hidden from screen readers. Afterglow announces nothing itself: the change is yours to announce, the same as without it.
- Dark surfaces get the light added on top (screen blend); light surfaces, judged from the element’s text colour, get it as colour, since white light on white shows nothing.
- Reduced motion skips the light entirely and runs the update at once.

License: MIT (https://hairlineui.com/license#components)
