# Reeded reveal

> A generated image seen through reeded glass: each reed bends its slice, then the glass clears from the centre outward.

A reveal with a material. While your generation runs, the frame is a pane of reeded glass with colour behind it and a glint crossing the reeds now and then. When the image has loaded you see it through the glass: every reed shifts and softens its own slice, as a cylinder lens does, and then the reeds relax from the centre outward while the glint sweeps once, until the picture is sharp, in 1.5s. It suits products with a crafted, premium feel. It needs no CORS.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/reeded-reveal.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): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/reeded-reveal
- Registry item (source): https://hairlineui.com/r/reeded-reveal.json

## Usage

```tsx
import { ReededReveal } from "@/components/reeded-reveal";

<ReededReveal
  src={image?.url}
  status={job.status}
  alt={prompt}
  onRetry={regenerate}
  className="aspect-square w-80"
/>
```

## Polling your generation API

Start a generation, poll its status, and hand the component the real state. Any API that reports generating, ready and failed works the same way.

```tsx
"use client";
import * as React from "react";
import { ReededReveal } from "@/components/reeded-reveal";

type Job = { id: string; status: "generating" | "ready" | "error"; url?: string; progress?: number };

export function Generation({ prompt }: { prompt: string }) {
  const [job, setJob] = React.useState<Job | null>(null);

  async function generate() {
    const { id } = await fetch("/api/generate", { method: "POST", body: JSON.stringify({ prompt }) }).then((r) => r.json());
    setJob({ id, status: "generating" });
    const poll = window.setInterval(async () => {
      const next: Job = await fetch(`/api/generate/${id}`).then((r) => r.json());
      setJob(next);
      if (next.status !== "generating") window.clearInterval(poll);
    }, 1000);
  }

  return (
    <div className="grid gap-3">
      <ReededReveal
        src={job?.url}
        status={job?.status ?? "generating"}
        alt={prompt}
        onRetry={generate}
        className="aspect-square w-80"
      />
      <button onClick={generate}>Generate</button>
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | – | The generated image. It can arrive before or with status "ready"; the reveal waits until it has loaded and decoded. |
| `status` | `"generating" \| "ready" \| "error"` | – | Your generation’s real state. Nothing plays on a timer. |
| `progress` | `number` | – | 0 to 1, if your API reports it. Shown as a small rolling figure; without it, no number is shown. |
| `alt` | `string` | – | The image’s text alternative, usually its prompt. |
| `crossOrigin` | `"anonymous" \| "use-credentials"` | – | Set it when your image host sends CORS headers. |
| `onReady` | `() => void` | – | Called once the reveal has played, or the image is shown without one. |
| `onRetry` | `() => void` | – | Shows Try again when the generation fails. |
| `labels` | `{ generating?, ready?, failed?, retry? }` | – | Words for the progress tag, the announcements and the failure. |
| `className` | `string` | – | Size the frame here, e.g. "aspect-square w-72". |
| `reeds` | `number` | `14` | How many reeds across the glass (4 to 40). |

## States

- **waiting**: Reeded glass (14 reeds by default) over two soft colour fields, with a glint crossing every 3.2s.
- **clearing**: Once the image has decoded: each reed shows its slice shifted up to 16px and squeezed by a third, frosted and shaded at its edges; the reeds relax from the centre outward over 1.5s while the glint sweeps once.
- **shown**: The plain image. onReady fires.
- **failed**: The pane with “This image couldn’t be created.” and Try again when onRetry is passed.

## What it handles

Loading states are usually generic grey; nothing about them belongs to the product.

- **A real material**: Every reed shifts and squeezes its own slice of the image, and its edges catch light, so it reads as glass, not a filter.
- **Clears from the centre**: The middle reeds relax first and the outer ones last, with one glint sweeping across.
- **Follows the real state**: It waits on your status and on the image decoding.
- **Sharp hand-over**: The glass is drawn at device resolution, so the real image takes over without a jump in sharpness.
- **Any image host**: It only draws the image, so it needs no CORS, and it avoids canvas filters Safari lacks.
- **Failure designed**: A failed generation says so with Try again.

## Replaces

loading spinner, skeleton loader, glass effect css, fade-in image

## Where it fits

- **Premium generators**: Image apps with a crafted, physical look.
- **Interior and architecture**: Renders arriving behind glass, the way they’re shown in studios.
- **Product shots**: Generated packshots and lifestyle photos.
- **Covers and posters**: Generated artwork landing in a card.

## Notes

- It follows your status: it waits while "generating", and plays only once status is "ready" and the image has loaded and decoded (img.decode), so it can never finish before the picture does. An image that was already there when the page loaded is simply shown.
- The figure has aria-busy while it waits, and a status line announces Generating, Image ready or the failure; the image keeps its alt text.
- The frosting is a tenth-size copy scaled back up, not a canvas filter, so it looks the same in Safari.
- Under reduced motion the image appears in place, with no drift while waiting.

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