Pixel Preloader
A fullscreen pixel-grid loader that takes over the viewport bottom-up behind a jagged orange frontier, with a top-left percentage HUD and a clean fade reveal.
Installation#
pnpm dlx shadcn@latest add @davinciui/pixel-preloaderUsage#
API Reference#
| Prop | Type | Default |
|---|---|---|
progressManual 0–100 override. Disables simulation; 100 triggers exit. | number | — |
durationMilliseconds for the simulated 0 → 100 progression (auto mode). | number | 4500 |
seedSeed for deterministic noise and spikes. | number | 1337 |
cellSizeTarget cell size in CSS pixels. | number | 6 |
backgroundColorUnloaded-region color. | string | theme-aware ("#0d0d0d" / "#d9d6d0") |
foregroundColorLoaded-region (warm white) color. | string | theme-aware ("#f3efe7" / "#faf8f3") |
themeColor scheme for the defaults. Auto follows the page and updates live; explicit colors always win. | "auto" | "light" | "dark" | "auto" |
accentColorTransition-frontier (orange) color. | string | "#ff4d23" |
showPercentageShow the top-left percentage HUD. | boolean | true |
completionHoldMilliseconds the completed 100% frame stays visible. | number | 450 |
exitDurationMilliseconds for the fade-out reveal. | number | 700 |
zIndexStacking order of the overlay. | number | 9999 |
onPhaseChangeFires on every transition: idle, loading, complete, exiting, finished. | (phase) => void | — |
onCompleteFires once the reveal finishes and the overlay unmounts. | () => void | — |
classNameAdditional classes for the overlay wrapper. | string | — |
Accessibility#
The overlay exposes role progressbar with aria-label Page loading and aria-valuenow updated on integer changes; canvas and HUD are aria-hidden and scroll is locked. It is not marked modal and moves no focus.
Motion#
The column frontier, spikes, percentage, and fade exit animate; duration, completionHold, and exitDuration control timing. matchMedia reduced motion caps loading at 500ms, skips column simulation, and shortens the fade, though HUD bars still pulse.
About Pixel Preloader#
A fullscreen pixel-cell loading takeover: a fine canvas grid fills bottom-up behind a jagged orange transition frontier with vertical spikes, while a small histogram + percentage HUD sits at the top-left.
At 100% the completed white frame holds briefly, then the overlay fades to reveal the page already mounted underneath. The frontier is a persistent per-column simulation — not television static — so consecutive frames read as the same terrain evolving.
Canvas renders every cell directly and the percentage only touches the DOM when the integer changes, so React never rerenders at 60fps. Noise is seeded, so the same seed replays the exact same pattern.
Behavior#
- Phases move through
idle → loading → complete → exiting → finished, then the overlay unmounts itself. - Auto mode simulates a staged progression — slow emergence, steady middle, eased landing near 100%.
- Manual mode follows the
progressprop (0–100) with smoothing, so hook it to real loading when available. - Theme — the field colors default to the page color scheme (near-black → white in dark mode, warm gray → white in light mode) and follow live theme changes; the orange frontier stays constant.
- Replay by remounting with a changing
key. - Scroll is locked while the overlay is alive and restored on exit.
- Reduced motion renders a calm frontier without spikes and shortens the sequence.
Best For#
Digital-first brand intros, developer tools, and launch pages where loading itself should feel like a procedural signal takeover.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

