Preloader Pro V5
A cinematic image preloader with masked typography, a seven-card 3D arc, featured full-bleed expansion, and split, lift, or iris reveals.
Installation#
pnpm dlx shadcn@latest add @davinciui/preloader-pro-v5Usage#
API Reference#
| Prop | Type | Default |
|---|---|---|
imagesPortrait images for the arc. The featured image can provide an expandSrc for the full-bleed crop. | (PreloaderProV5Image | string)[] | 8-image editorial set |
imageCountNumber of arc cards. Responsive breakpoints cap the count at 5 on mobile and 6 on tablet. | number | 7 |
featuredIndexImage that converges, expands to full bleed, and drives the final reveal. | number | 3 |
brandNameBrand title revealed before the arc and over the image. | string | "DaVinci UI" |
introTextOpening masked line shown before the brand title. | string | "Every interface, considered." |
themeColor scheme for the default palette. Auto follows the page dark class, data-theme, or system preference and updates live. | "light" | "dark" | "auto" | "auto" |
logoOptional logo rendered above both brand titles. Strings that look like image URLs render as an image. | ReactNode | — |
fontFamilyFont stack applied to the overlay. | string | site sans stack |
textColorIntro and brand title color. | string | light "#111111" / dark "#F1EEE8" |
imageTextColorBrand title color over the expanded image. | string | "#ffffff" |
imageWidthBase arc card width before responsive scaling. | number | 240 |
imageHeightBase arc card height before responsive scaling. | number | 320 |
imageRadiusArc card and feature corner radius. | number | 10 |
imageFitObject fit for arc and feature images. | "cover" | "contain" | "cover" |
imagePositionDefault object position, overridable per image with position. | string | "50% 50%" |
backgroundColorOverlay background color. | string | light "#ECECEA" / dark "#0B0B0A" |
cardBackgroundCard placeholder color while images decode. | string | light "#d8d5cf" / dark "#23211E" |
overlayColorScrim color over the expanded image. | string | light "rgba(7, 7, 7, 0.22)" / dark "rgba(0, 0, 0, 0.38)" |
titleSizeBrand title font size. | number | string | clamp(2rem, 8.5vw, 8rem) |
introTextSizeIntro line font size. | number | string | clamp(1.6rem, 5.6vw, 5.2rem) |
imageGapGap between cards along the arc. | number | 26 |
arcRadiusArc radius before responsive clamping. | number | 720 |
animationDurationSeconds from intro to the start of the exit reveal. | number | 7.4 |
staggerDelayPer-card stagger between arc entries. | number | 0.09 |
cardMovementSpeedScales arc entry speed without changing the overall duration. | number | 1 |
transitionDurationSeconds for the selected exit reveal. | number | 1.05 |
animationEasingCSS easing string used for the exit reveal. Accepts linear, ease keywords, or cubic-bezier. | string | "cubic-bezier(0.22, 1, 0.36, 1)" |
revealStyleExit reveal: split image halves, lift the overlay upward, or close a circular iris. | "split" | "lift" | "iris" | "split" |
playOnEveryLoadPlay on every mount. Set false to treat the loader as session bound. | boolean | true |
playOncePerSessionStore a sessionStorage flag and skip the loader on later mounts. | boolean | false |
disableScrollDuringPlaybackLocks page scroll while the overlay is active and restores it on exit. | boolean | true |
skipPreloaderRender nothing and complete immediately. | boolean | false |
sessionKeysessionStorage key used by the session flags. | string | "preloader-pro-v5-shown" |
onCompleteFires once the overlay leaves and unmounts. | () => 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 | 5 |
zIndexOverlay stacking order when not in preview mode. | number | 99999 |
Accessibility#
A role status with aria-live polite announces the intro, brand, and reveal phases while the arc cards and image title are aria-hidden. Scroll is locked while active, Escape skips the loader, and the overlay is not modal and moves no focus. Reduced-motion users get a static composed arc with a short fade.
Motion#
A single requestAnimationFrame timeline derives the masked intro and title, staggered arc entry, orbit drift, convergence, featured expansion, image title, split phase, and split, lift, or iris exit; animationDuration, staggerDelay, cardMovementSpeed, transitionDuration, and animationEasing control timing. matchMedia reduced motion shows a static composed arc with a short opacity fade.
About Preloader Pro V5#
A cinematic editorial preloader: masked words trade places while seven portrait stills sweep into a wide 3D arc, converge on a featured image, and open into a split-image reveal.
The sequence is built from flat DOM elements. A single requestAnimationFrame timeline drives the card arc, orbit drift, featured expansion, and final reveal, so the loader stays deterministic and can be scrubbed or replayed.
Add an optional expandSrc to the featured image for a dedicated full-bleed crop. Every color, size, arc value, and timing constant is exposed as a prop.
Behavior#
- Masked typography lifts the intro line character by character, then trades it for the brand name before the images arrive.
- Arc entry sends each portrait from below the viewport into a shallow 3D arc with perspective yaw, per-card stagger, and orbit drift.
- Convergence collapses the arc toward the centre while the non-featured cards fade back.
- Featured expansion scales the selected card to full bleed, swaps in
expandSrcwhen available, and adds an overlay scrim for the image title. - Split reveal (revealStyle="split") opens a horizontal gap through the image before the overlay leaves the page.
- Exit styles:
splitseparates the image halves,liftslides the whole overlay upward, andiriscloses a circular mask. - Playback controls: scroll is locked while active, Escape skips, and the ref handle exposes `replay()`, `skip()`, and `seek(t)`.
- Session and motion: play once per session, skip on every load, or let reduced-motion users see a static composed frame with a short fade.
- Preview mode renders one frozen frame for gallery cards and docs surfaces without timers.
Best For#
Photography portfolios, fashion editorials, film and studio sites, and launch pages where a small set of images should feel like a printed sequence 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.

