Loading…

Grid Reveal

beta

A loading frame for a generated image: it opens as four shimmering cells, keeps splitting its largest cell as the wait goes on, then resolves cell by cell — busiest detail first — into the real picture.

AI
1 file
2 npm packages
Accessibility notes
Draws on a canvas

Playground

Installation

The CLI installs shimmer-text as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add grid-reveal

npm packages installed: class-variance-authority, motion.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

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

Examples

Every example the tests run, live and operable, side by side.

Default
Generate
Controlled Progress
Aspects
Gutters
Revealed

API

Generated from the component's own types, so a prop cannot appear here without existing.

<GridReveal>

Prop	Type	Default
`alt` Describes the finished image. Without it the frame is hidden from assistive technology.	`string`	—
`aspect` Width ÷ height of the frame. It fills its parent's width, so size the parent.	`number`	`1`
`caption` Status text in a frosted pill at the bottom-start of the frame. Changes cross-fade.	`string`	—
`crossOrigin` Forwarded to the images. Set "anonymous" for a CORS-enabled host so the reveal order can read the pixels.	`"anonymous" \| "use-credentials"`	—
`estimatedDuration` Roughly how long the work takes, in ms, to pace the grid without `progress`. Overrunning is fine.	`number`	`10000`
`gutter`	`"none" \| "sm" \| "md"`	`"sm"`
`onError` Fires when the image fails to load. The grid keeps waiting, so show your own fallback.	`() => void`	—
`onRevealComplete` Fires once the image has fully resolved.	`() => void`	—
`progress` How far through the wait, 0–1; drives how far the grid has split. Held at 0.72 until the image decodes. Omit it to pace the grid by `estimatedDuration`.	`number`	—
`src` The image to reveal. Keep it null while the image is generating — the grid only runs while it is empty, and a src that is already loaded makes the whole run flash by.	`string \| null`	`null`

Plus every attribute of <div> except children, onError.

Accessibility

The frame is aria-busy until the picture is complete, then exposes a single <img> carrying `alt`; the cells, the per-cell pieces and the not-yet-shown image are aria-hidden throughout. Without `alt` the whole frame is decorative and hidden from assistive technology. The caption is plain text, not a live region — announce completion yourself from onRevealComplete if the page needs it. Under reduced motion the shimmer stops, splits happen without the spring (MotionConfig reducedMotion="user") and the reveal completes almost at once.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

alt

Describes the finished image. Without it the frame is hidden from assistive technology.

string

—

aspect

Width ÷ height of the frame. It fills its parent's width, so size the parent.

number

1

caption

Status text in a frosted pill at the bottom-start of the frame. Changes cross-fade.

string

—

crossOrigin

Forwarded to the images. Set "anonymous" for a CORS-enabled host so the reveal order can read the pixels.

"anonymous" | "use-credentials"

—

estimatedDuration

Roughly how long the work takes, in ms, to pace the grid without progress. Overrunning is fine.

number

10000

gutter

"none" | "sm" | "md"

"sm"

onError

Fires when the image fails to load. The grid keeps waiting, so show your own fallback.

() => void

—

onRevealComplete

Fires once the image has fully resolved.

() => void

—

progress

How far through the wait, 0–1; drives how far the grid has split. Held at 0.72 until the image decodes. Omit it to pace the grid by estimatedDuration.

number

—

src

The image to reveal. Keep it null while the image is generating — the grid only runs while it is empty, and a src that is already loaded makes the whole run flash by.

string | null

null