Fill Preloader
A fullscreen bottom-up blue fill loader with a giant bottom-right percentage counter and a vertical slide-away reveal.
Installation#
pnpm dlx shadcn@latest add @davinciui/fill-preloaderUsage#
API Reference#
| Prop | Type | Default |
|---|---|---|
backgroundColorFullscreen background color behind the fill. | string | theme-aware ("#111111" / "#e8e6e3") |
fillColorSolid color of the rising progress surface. | string | "#0b5ffb" |
textColorColor of the percentage counter. | string | theme-aware ("#ffffff" / "#09090b") |
themeColor scheme for the defaults. Auto follows the page and updates live; explicit colors always win. | "auto" | "light" | "dark" | "auto" |
durationMilliseconds for the simulated 0 → 100 progression (auto mode). | number | 2800 |
completionHoldMilliseconds the completed 100% frame stays visible. | number | 300 |
exitDurationMilliseconds for the vertical exit reveal. | number | 900 |
progressManual 0–100 override. Disables simulation; 100 triggers exit. | number | — |
showCounterShow the bottom-right percentage counter. | boolean | true |
fontSize / fontWeight / fontFamilyCounter typography. | string / number / string | clamp(64px, 9vw, 132px) / 600 / inherit |
counterOffsetX / counterOffsetYCounter distance in pixels from the right and bottom edges (safe-area aware). | number | 32 / 24 |
zIndexStacking order of the overlay. | number | 100 |
onPhaseChangeFires on every transition: idle, loading, complete, exiting, finished. | (phase) => void | — |
onCompleteFires once the exit 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 as progress changes. The visible percentage counter and fill are aria-hidden, scroll is locked, and there is no keyboard dismiss or skip control.
Motion#
Framer Motion animates the blue fill via scaleY and slides the overlay up on exit using a fixed cubic-bezier ease. duration, completionHold and exitDuration set timing; useReducedMotion caps progress at 400ms and exit at 250ms while keeping the same sequence.
About Fill Preloader#
A fullscreen loading transition: a solid blue surface rises from the bottom over a near-black screen while a large percentage counter sits anchored at the bottom-right.
At 100% the completed frame holds briefly, then the entire overlay slides vertically upward — a clean reveal with no fade. Your page content already exists underneath; the preloader is purely an overlay covering it.
One motion value drives both the blue fill and the counter, so they can never drift apart. The fill uses GPU-friendly scaleY transforms and the counter updates imperatively — React never rerenders at 60fps.
Behavior#
- Phases move through
idle → loading → complete → exiting → finished, then the overlay unmounts itself. - Auto mode simulates a natural staged progression — slow start, fast middle, eased landing near 100%.
- Manual mode follows the
progressprop with smoothing, so hook it to real loading when available. - Theme — background and counter default to the page color scheme (light or dark) and follow live theme changes; the blue fill stays constant.
- Replay by remounting with a changing
key. - Scroll is locked while the overlay is alive and restored on exit.
- Reduced motion shortens the simulation and exit while keeping the same sequence.
Best For#
Portfolio intros, campaign pages, and product launches where the first paint should feel like a confident editorial curtain-lift.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

