Preloader Pro V4
A seven-card editorial preloader with a rising pile, fanned arc, percentage counter, centre-card lift, and a full-bleed 16:9 image expansion.
Installation#
pnpm dlx shadcn@latest add @davinciui/preloader-pro-v4Usage#
API Reference#
| Prop | Type | Default |
|---|---|---|
cardsCard images rendered in order. Up to 15 are supported. The featured card can provide a 16:9 expandSrc for the fullscreen crop. | { src: string; expandSrc?: string; title?: string }[] | 7-image editorial set |
featuredIndexCard that lifts and expands into a 16:9 frame that covers the viewport. | number | middle card |
featuredTitleOptional title reserved for the featured card in future caption variants. | string | — |
labelTop-left label, uppercased by CSS with wide letter spacing. | string | "Loading" |
modeTimed uses the measured two-second counter curve; pageLoad follows image decoding and document load events. | "timed" | "pageLoad" | "timed" |
durationSeconds for the counter progression. The lift and exit phases shift with this value. | number | 2 |
exitOverlay exit: a 0.45s opacity fade or a 0.7s upward slide. | "fade" | "slide-up" | "fade" |
themePalette mode. Auto follows the site light/dark class; light uses warm paper and dark ink. | "auto" | "light" | "dark" | "auto" |
backgroundOverlay background override. Defaults to the active theme palette. | string | theme palette |
textColorCounter and primary foreground override. Defaults to the active theme palette. | string | theme palette |
mutedColorLabel and dimmed counter override. Defaults to the active theme palette. | string | theme palette |
counterFontCounter font stack. | string | "Inter Tight", … |
labelFontTop-left label font stack. | string | "Inter Tight", … |
cardWidthBase card width at 1465px. Scales with the viewport and preserves a 5:7 aspect ratio. | number | 170 |
spreadRotation between adjacent cards in degrees, capped as the card count grows. | number | 12.5 |
radiusCard corner radius, scaled with card width. | number | 14 |
rippleIntensityScales the travelling vertical ripple during the counter phase. Zero disables it. | number | 1 |
waveCountNumber of interleaved ripple waves passing through the fan. | number | 1 |
lockScrollLocks page scroll while the overlay is active and marks the underlying main element inert. | boolean | true |
oncePerSessionStores a sessionStorage flag when the exit starts and skips the loader on later mounts. | boolean | false |
onCompleteFires after the overlay leaves and is removed from the tree. | () => void | — |
previewRenders one frozen frame with no timers, used by gallery cards and docs surfaces. | boolean | false |
previewTimeTimeline time used when preview is enabled. | number | 1.6 |
Accessibility#
A role status with aria-live polite announces 0, 25, 50, 75, and 100 percent loaded, while the fan, counter, label, and expanding image are aria-hidden. Scroll is locked and the underlying main is marked inert while active, but the overlay is not modal, traps no focus, and offers no skip control; reduced-motion users get a static frame and a short fade.
Motion#
A single requestAnimationFrame timeline derives the rising column, spring fan, ripple, power-curve counter, lift, real-rect expansion, and fade or slide exit; duration, exit, spread, rippleIntensity, and waveCount control timing. matchMedia reduced motion shows a static composed fan with a short opacity fade.
About Preloader Pro V4#
A seven-card editorial loader: portrait stills rise from the lower edge, collapse into a centred pile, then fan into a shallow arc while the counter climbs from 000 to 100.
At the top of the count the centre card lifts, pauses, and expands into a full-bleed 16:9 image before the overlay cuts away to the page. Add an optional expandSrc to the featured card for a dedicated landscape crop. The composition is built from flat DOM elements — no canvas, WebGL, or 3D transforms.
One requestAnimationFrame timeline drives the whole sequence. Card positions, ripple, lift, expansion, counter, and exit all read from elapsed time, so the loader stays deterministic and can be scrubbed or replayed.
Behavior#
- Rise and fan starts as a tight column at the bottom edge, collapses at centre, then springs into a 12.5° arc with the featured card on top.
- Counter follows the measured curve and eases into 100 around 2.13s, well before the lift begins.
- Ripple sends a short vertical bump through the fan during the count, offset per card and scaled by
rippleIntensity. - Lift and expand raises the featured card by 115px at 1.14× scale, holds, then animates its real rectangle to the viewport with
object-fit: cover. - Exit is a 0.45s fade by default.
exit="slide-up"lifts the whole overlay away over 0.7s. - Theme aware by default: the overlay follows the site light/dark class, so light mode uses warm paper with dark ink and dark mode keeps the near-black palette. Set
themeto lock a palette. - Reduced motion skips the fan, ripple, lift, and expansion, showing a static composed frame with a short fade.
- Page load mode follows image decoding and document load events instead of the timed curve.
- Replay with the exposed `replay()` ref handle, or scrub with `seek(t)`.
Best For#
Fashion editorials, photography portfolios, and launch pages where a small set of images should feel like a printed contact sheet opening into a single hero frame.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

