Grid Reveal React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import GridReveal from @/components/ui/grid-reveal.

"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

• aspectdefault 1
  number

  Width divided by height of the frame. The frame fills its parent's width, so constrain the parent to size it.

• captiondefault ""
  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.

• altdefault ""
  string

  Describes the finished image for screen readers. The frame is hidden from assistive tech when it is empty.

• estimatedDurationdefault 6000
  number

  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.

• cellsdefault 180
  number

  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.

• radiusdefault 16
  number

  Corner radius of the frame in pixels, drawn as a squircle where the browser supports corner-shape.

• captionPositiondefault "bottom-left"
  "bottom-left" | "bottom-right" | "top-left" | "top-right"

  The corner the caption pill sits in, 12px from the edges.

• captionColordefault "rgba(0, 0, 0, 0.45)"
  string

  Any CSS color for the caption pill, drawn over a blur.

• shimmerdefault true
  boolean

  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%.

• srcdefault ""
  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.

• progressdefault 0
  number

  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.

FAQ

More React AI components