Grid Loader
A compact 5×5 status loader driven by six original compiled trajectories.
Grid Loader is a loading indicator for AI interfaces: a 5×5 dot grid that plays six compiled trajectories while an agent thinks, streams, or works. It is a React component built with shadcn/ui and Tailwind CSS.
Trajectory compiler
Each recipe declares continuous geometry, a duration, and a tail length. Grid Loader samples that geometry by arc length, snaps it onto the 5×5 matrix, and bridges the result into a closed sequence of neighboring cell visits. At runtime, a bright head and directional fading tail travel over that compiled sequence. Repeated visits and multi-path recipes are combined without normalizing away their visual emphasis.
Variants
sweeppairs a horizontal triangle-wave scan with a vertical turnaround.tracefollows a compact four-petal rose curve.spiraltravels two turns outward before folding back inward.ribbondraws a 2:3 Lissajous ribbon through the matrix.classifyingsends mirrored paths apart, around, and back together.orbitfollows an elliptical loop with three radial pulses.
All six recipes are original to Vivid Layer and use the same fixed 5×5 DOM renderer. They differ only in their continuous trajectory, tail length, and default duration.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "sweep" | "trace" | "spiral" | "ribbon" | "classifying" | "orbit" | "orbit" | Selects one of the six motion recipes. |
size | number | 16 | Sets the square component size in pixels. |
dotSize | number | 2 | Sets each circular dot size in pixels. |
duration | number | variant duration | Overrides the selected recipe duration in milliseconds. |
label | string | undefined | Names the loader and exposes it as a status. Without a label, the loader is decorative. |
className | string | undefined | Styles the wrapper and supplies its current color. |
Other native span props are forwarded to the wrapper. The component owns
children and its status-related ARIA attributes.
Runtime
Every mounted Grid Loader shares one requestAnimationFrame scheduler. Frames
sample the precompiled cell visits, write opacity directly to the fixed 25
dots, and do not trigger React renders. The component has no third-party runtime
dependency beyond React and the local cn utility.
When reduced motion is requested, animation stops and each variant renders a balanced static representative pattern instead of freezing an arbitrary frame.