# Grid Reveal

> A React AI image loading placeholder: a canvas grid that splits while the image generates, then resolves into the real picture.

- Type: React component (AI Kit)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add grid-reveal`
- Docs: https://wingo-ui.com/components/grid-reveal

## Interaction

Press Generate and the frame opens as four cells, then keeps splitting the biggest one in two while the image is on its way. When the picture lands the cells take on its colors, busy parts of the image split first, the gutters close up and the photo fades in. A frosted status pill sits in the bottom left with a slow shimmer, crossfading between lines as the caption changes, and fades out once the reveal is done. Honors prefers-reduced-motion by holding a still frame.

## Installation

```bash
npx wingo-ui@latest add grid-reveal
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/grid-reveal.json`

Files:

- `components/ui/grid-reveal.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
"use client"

import { useState } from "react"
import GridReveal from "@/components/ui/grid-reveal"

export function Demo() {
  const [src, setSrc] = useState<string | null>(null)

  async function generate() {
    setSrc(null)                   // null is the waiting state, the grid runs while it is empty
    setSrc(await createImage())    // setting it resolves the grid into the picture
  }

  return (
    // the frame fills its parent, so give the parent a width
    <div className="w-64">
      <GridReveal src={src} alt="Generated image" caption="Creating image" />
      <button onClick={generate}>Generate</button>
    </div>
  )
}

// Passing a src that is already loaded skips the wait, so the run flashes by.
// Pass progress when your API reports it: <GridReveal src={src} progress={job.progress} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aspect?` | `number` | `1` | Width divided by height of the frame. The frame fills its parent's width, so constrain the parent to size it. |
| `caption?` | `string` | `""` | Optional status text, shown as a frosted pill in the bottom left of the frame and lit by a slow shimmer. Change it mid-run and the lines crossfade while the pill resizes to suit. Empty renders no pill. |
| `alt?` | `string` | `""` | Describes the finished image for screen readers. The frame is hidden from assistive tech when it is empty. |
| `estimatedDuration?` | `number` | `6000` | Roughly how long the work takes in milliseconds, used to pace the grid when no progress is passed. Overrunning it is fine, the grid keeps creeping instead of stopping. |
| `cells?` | `number` | `180` | How many cells the grid ends on before the photo fades in, from 8 to 400. Fewer cells read as big bold blocks, more as a fine mosaic. A new count shows on the next reveal. |
| `radius?` | `number` | `16` | Corner radius of the frame in pixels, drawn as a squircle where the browser supports corner-shape. |
| `captionPosition?` | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `"bottom-left"` | The corner the caption pill sits in, 12px from the edges. |
| `captionColor?` | `string` | `"rgba(0, 0, 0, 0.45)"` | Any CSS color for the caption pill, drawn over a blur. |
| `shimmer?` | `boolean` | `true` | Sweeps a highlight across the caption text while the image is on its way. Off (and under reduced motion) the text is plain white at 75%. |
| `src?` | `string \| null` | `""` | Image to reveal. Keep it null while the image is generating, since the grid only runs while this is empty and a src that is already loaded makes the whole run flash by. Cross-origin images need CORS headers for the color pass; without them the grid stays grey and the photo still fades in. In the playground an image URL replaces the sample when the wait is over. |
| `progress?` | `number` | `0` | Position of the wait from 0 to 1, driving how far the grid has split. It holds at 0.72 until the image decodes, and the image landing is what finishes the reveal. Leave it out to pace by estimatedDuration. |
| `onRevealComplete?` | `() => void` |  | Fires once the image has fully resolved. |
| `onError?` | `() => void` |  | Fires when the image fails to load. Without it a broken src leaves the grid waiting, so use it to show your own fallback. |
| `className?` | `string` |  | Extra classes merged onto the root element (data-slot="grid-reveal"). Other div props are spread onto it too. |
| `style?` | `React.CSSProperties` |  | Inline styles merged after the aspect ratio, so an aspectRatio here overrides the aspect prop. |

## Examples

- **Driven by your API's progress**: Pass progress (0 to 1) when your job reports it and the grid splits in step with it instead of pacing itself by estimatedDuration. Setting src is what completes the reveal.
- **A batch of four**: Four generations in a grid, each finishing at its own time. Fewer cells (64) and a smaller radius read better at thumbnail size.
- **Wide header with a corner caption**: A 16:9 frame with a fine 300-cell mosaic, a 24px radius and the caption pill in the top right corner.
- **Inside a chat reply**: The assistant's message holds the frame while the image renders, then swaps its text once the picture lands.

## See also

- [Skeleton](https://wingo-ui.com/components/skeleton) ([Markdown](https://wingo-ui.com/components/skeleton.md))
- [Matrix Orb](https://wingo-ui.com/components/matrix-orb) ([Markdown](https://wingo-ui.com/components/matrix-orb.md))
- [Fluid Orb](https://wingo-ui.com/components/fluid-orb) ([Markdown](https://wingo-ui.com/components/fluid-orb.md))
- [Reasoning Indicator](https://wingo-ui.com/components/reasoning-indicator) ([Markdown](https://wingo-ui.com/components/reasoning-indicator.md))
- [Progress](https://wingo-ui.com/components/progress) ([Markdown](https://wingo-ui.com/components/progress.md))
- [Chat Message](https://wingo-ui.com/components/chat-message) ([Markdown](https://wingo-ui.com/components/chat-message.md))

---

Canonical: https://wingo-ui.com/components/grid-reveal
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt